README
¶
Plums
Open source AI agent TUI.
Very early WIP.
Install
go install github.com/Ceinl/plums/cmd/plums@latest
Prerequisites
- Go 1.26.2+
opencodefor the default backendcodexonly when using the Codex backend
Run
plums
Useful flags:
-version-provider opencode|codex-server-url URL-init-config-no-config-doctor
Config
plums is global-only, neovim style. On first launch, plums seeds a compiled Go
config at ~/.config/plums/config/config.go when one is missing. You can also
seed it explicitly:
plums -init-config
The user-authored config directory is ~/.config/plums/config:
config.go— the compiled Go config (config.Use); edit this to reshape plums. Launchingplumsauto-compiles it (cached) and runs the result;plums buildbuilds it explicitly.go.mod/go.sum— the managed config module. plums creates these; normal Go tooling works inside this directory.plugins/— local user plugins scaffolded byplums plugin new.
Runtime preferences that opt into cfg.Dynamic are stored separately in the
app-managed ~/.config/plums/state.toml; it is not a user config format.
The bundled layout plugin ships only zen. The seeded config.go adds split
as a user plugin — run plums -doctor to see zen (ui/layouts) and
split (split-layout).
Plugins
Create a local plugin in the config module:
plums plugin new hello
This creates ~/.config/plums/config/plugins/hello, adds a plugintest smoke
test, and wires hello.New(hello.Options{}) into config.go. Use
--no-wire if you want to edit config.go manually.
Add a remote plugin module:
plums plugin add github.com/example/plums-thing@latest
This runs go get and go mod tidy in the config module, then wires the
package into config.go using the same New(Options{}) convention. If a plugin
uses a different constructor shape, rerun with --no-wire and edit config.go.
Other plugin commands:
plums plugin list
plums plugin update
plums plugin update github.com/example/plums-thing
Development
go test ./...
go build ./...
Directories
¶
| Path | Synopsis |
|---|---|
|
Package capabilities holds the plums plugin floor: the capability interfaces and domain types that plugin authors implement and consume.
|
Package capabilities holds the plums plugin floor: the capability interfaces and domain types that plugin authors implement and consume. |
|
cmd
|
|
|
plums
command
|
|
|
Package config is the public authoring surface for a plums user config.
|
Package config is the public authoring surface for a plums user config. |
|
internal
|
|
|
builtincfg
Package builtincfg is the App's built-in Default Config.
|
Package builtincfg is the App's built-in Default Config. |
|
core/backend/streambridge
Package streambridge holds the shared translation helpers every backend bridge uses to convert a provider's native types into the public capabilities types: Forward for the streaming event channel, Map for List* slice results.
|
Package streambridge holds the shared translation helpers every backend bridge uses to convert a provider's native types into the public capabilities types: Forward for the streaming event channel, Map for List* slice results. |
|
core/harness
Package harness is experimental and outside the private beta scope.
|
Package harness is experimental and outside the private beta scope. |
|
ui/tui/theme
Package theme is the single source of truth for the TUI colour palette.
|
Package theme is the single source of truth for the TUI colour palette. |
|
plugins
|
|
|
backend
Package backend owns backend/model selection commands for the default config.
|
Package backend owns backend/model selection commands for the default config. |
|
commands
Package commands is the built-in command plugin.
|
Package commands is the built-in command plugin. |
|
gitdiff
Package gitdiff is the default provider for the split-pane Git diff view.
|
Package gitdiff is the default provider for the split-pane Git diff view. |
|
layouts
Package layouts is the built-in layout plugin.
|
Package layouts is the built-in layout plugin. |
|
questions
Package questions owns default question prompt rendering and answer parsing.
|
Package questions owns default question prompt rendering and answer parsing. |
|
sessions
Package sessions owns session commands for the default config.
|
Package sessions owns session commands for the default config. |
|
skills
Package skills is the default skills plugin.
|
Package skills is the default skills plugin. |
|
tmux
Package tmux owns terminal integration that tweaks tmux for the app run.
|
Package tmux owns terminal integration that tweaks tmux for the app run. |
|
plums
|
|