--- title: "Configuration" description: "Settings, the key tables, upgrading from config.toml, how the built-in CLIs are kept current, themes, and where state is kept." canonical: "https://agent-manager.dev/docs/config/" last-updated: "2026-10-25" section: "Documentation" source: "agent-manager" --- # Configuration Everything you can change lives in Settings (`s`): the keys, the editor `o` opens, the theme and the rest of its rows. Changes are saved as you leave Settings and take effect at that moment. Only the rows you changed are written, so a change another manager or the CLI made in the meantime is kept. Every CLI's launch command, resume and fork commands, MCP registration and status rules live in the binary, so an upgrade brings the current version of all of them. The manager stores each choice in `state.db`, a SQLite file in your OS user config directory: | Platform | Directory | | --- | --- | | Linux | `~/.config/agent-manager/`, or under `$XDG_CONFIG_HOME` when that is set. | | macOS | `~/Library/Application Support/agent-manager/` | | Windows | `%AppData%\agent-manager\` | The `editor` row picks the command `o` opens a directory in. `←→` steps through `auto`, each GUI editor found on your `PATH`, the editors `$VISUAL` and `$EDITOR` name, and `custom`, where `↵` opens a field for a command of your own. `auto` resolves to `$AGENT_MANAGER_EDITOR`, then a GUI editor on `PATH`, then `$VISUAL` / `$EDITOR`. On Linux, a link opens in `$BROWSER` when you set one, colon-separated with `%s` for the URL, falling back to `xdg-open`. macOS hands links to `open`. Panes are polled every two seconds for status, preview and stats. ## Settings from a shell `agent-manager settings` reads and changes the same settings without opening the manager. `settings list` prints every key with its value and the values it takes. `settings get` prints one, the default when none is stored, and `settings set` writes one. A value outside that key's choices is refused, and the refusal names the choices. ```bash agent-manager settings set theme "tokyo night" agent-manager settings set notifications off agent-manager settings get list_density ``` A running manager picks up `notifications`, `coordination` and `notify_command` at once. The rest show the next time Settings opens, and apply from then on. `notify_command` has no Settings row. [Status](/docs/status/#notifications) covers it. ## Saved prompts The `saved prompts` row in Settings keeps named instructions you reuse. `n` creates one, `enter` edits it and `d` deletes it. `tab` moves between the name and the text, `ctrl+s` saves and `esc` backs out. Names are unique, up to 60 characters, with no brackets, and the text is up to 64 KiB. One list serves the `n` form, quick prompt mode, a focused session, `spawn --saved`, `send --saved`, and `saved` on `create_session` and `send_session`. [Quick prompt](/docs/prompt/#saved) shows where each one goes. ```bash agent-manager prompts list agent-manager prompts add reviewer "Review the parser changes" agent-manager prompts rm reviewer ``` Changing or deleting one leaves a session that already started alone. ## Upgrading from config.toml Releases before v0.40.0 read a `config.toml` in that directory. The first start after upgrading carries its `editor` line and its `[keybindings.session]` and `[keybindings.list]` tables into Settings, so every key you moved stays where you put it. That happens once. From then on Settings is the only place the manager reads, and the file is yours to delete. A file the manager cannot read is named in Messages (`M`) with the reason, and the keys start from the defaults. The poll interval is fixed at two seconds, so a `poll_interval` line in that file has no effect. `[tools.]` blocks have none either, since every CLI's commands and status rules are built into the binary. ## The CLIs Claude Code, OpenCode, Codex, Grok Build, Gemini CLI, Antigravity CLI, Pi, Command Code, Hermes Agent, Muse Code, Oh My Pi and Cursor CLI are built in, plus the shell `T` opens. Each one's launch command, revive and fork commands, MCP registration, status rules, and the flags a session's model, effort and profile launch with ship in the binary. Hermes, Antigravity, Oh My Pi and Cursor CLI have no fork, and Pi and Oh My Pi get no MCP registration. Settings (`s`) has a `CLIs` row that picks which of them the `n` form and quick prompt mode offer, and its last entry, `request CLI support`, opens an issue prefilled for a CLI outside the list. [Supported agents](/docs/agents/) lists what each one gets. Agent Manager supports the current release of each CLI. A CLI can also carry the oldest release it still works with. When yours is older, a spawn, a revive or its model list opens a dialog that names your version, the one it needs, and the vendor installer that updates it. `i` runs that installer and `c` copies it. A CLI under `/nix/store` gets no installer, and the dialog says to update it the way it was installed. Pi needs 0.84.3 or later. No other CLI has a floor yet. ## When a status reads wrong The rules are ours to fix, for everyone. Read the pane the way the poller reads it, with the session id in place of `SESSION_ID`, and [open an issue](https://github.com/YoanWai/agent-manager/issues/new/choose) with that text and the CLI's version: ```bash tmux -L agentmgr capture-pane -p -t am_SESSION_ID ``` ## Key bindings The `keybindings` row in Settings opens one picker with two tables: the keys the manager keeps inside a session, and the keys of its own list. Each action takes one key or several, and an action can be turned off. One key serves one action within a table. `↵` binds the key you press next, `a` adds a second key to an action, `d` turns the action off, and `r` names what would move and asks, then puts the shipped keys back on every action. A key its table cannot take is refused there with the reason. Leaving the picker stores each table you changed and puts the keys to work at once. Only a key you moved is stored, so an action at its shipped default follows that default when a release changes it. The session actions are `detach` (default `ctrl+q` and `ctrl+\`), `review` (default `ctrl+r`), `editor` (default `f3`), `saved_prompt` (default `f4`) and `tmux_prefix` (off by default). A session key is `ctrl+` a letter, `alt+` a letter or digit, or `f1` to `f12`, since a bare character would take it away from the agent. `detach` always keeps at least one key. `tmux_prefix` gives managed sessions a tmux prefix of their own, one key or two, so the key your own tmux.conf uses as its prefix is free to be a session key, `detach` for one. The list actions are `up`, `down`, `open`, `attach`, `step_in`, `step_out`, `reorder_up`, `reorder_down`, `new_session`, `terminal`, `new_group`, `fork`, `prompt`, `copy_reply`, `review`, `mark_idle`, `rename`, `move`, `editor`, `restart`, `kill`, `kill_all`, `revive`, `revive_all`, `archive`, `cancel_end`, `restore`, `delete`, `search`, `filter`, `archived`, `empty_groups`, `fold_all`, `resize`, `settings`, `messages`, `help`, `quit` and `new_connection`. A list key is a plain character, a key name such as `space` or `pgup`, `shift+` an arrow or tab, or the modifier forms above. `esc` and `ctrl+c` stay as they are. `esc` cancels everywhere. `ctrl+c` quits the manager even with `quit` turned off, and a focused session sends it to the agent. `settings` keeps at least one key. The same tables drive a full-screen attach and focus mode, and a session created from the `agent-manager` CLI or by an agent through the MCP server carries them too. The footer, the `?` key map and the session footers all read the tables, so a moved key is named where it moved to. ## Themes `s` opens settings, where `↑↓` or the wheel move between fields and `←→` change the focused one. A click on a row moves to it, and a second click changes it or runs it. `save and close` is a footer key like the others: `esc` runs it, `enter` runs it on a row with no action of its own, and so does a click on it. Eighteen palettes ship. Eleven dark: classic, solarized dark, catppuccin mocha, tokyo night, gruvbox dark, nord, dracula, rosé pine, monochrome, kanagawa wave and onedark. Seven light: solarized light, catppuccin latte, tokyo night day, gruvbox light, rosé pine dawn, paper and kanagawa lotus. The swatch strip beside the name previews the palette, and the theme applies as you step through the picker, so it is a live preview of the whole UI. The manager also sets the terminal's own text and background colors to the palette's, so the window has no seam against it, and restores them on exit. Agent panes render on the theme's own backdrop and text color, and the pane declares both to the agent inside it, so an agent that auto-detects its palette lands on the same side the manager is drawing. **theme follows OS** resolves the palette at startup from the environment's light/dark preference: the OS setting on macOS and Linux desktops, and the terminal's own background elsewhere, SSH included. A theme already on the detected side stays; only a mismatch switches. A palette with a light and a dark variant switches to its other half, so catppuccin mocha turns into latte and back, and any other palette switches to classic or solarized light. Your manual pick is kept separately, so turning the toggle off returns to it. **background** picks what fills the cells behind the UI. `theme`, the default, paints them in the palette's colors, so they hold on a terminal that ignores the color request. `terminal` leaves them on the terminal's own colors, for a translucent or blurred window. ### Symbols **symbols** switches between **Advanced**, the default, and **Compatible**, plain ASCII marks for a font that cannot draw the geometric ones. Compatible covers the status marks, the loader, the inbox, drag handles, group folds, terminal rows, worktree and fork marks, the prompt and reply prefixes, search, dialog titles, notices, pending archives and kills, and diff outcomes. The row previews the marks as you step it, and the choice applies at once. Fonts are not detected. Borders, gauges, arrows, key hints and agent output stay as they are. [Status](/docs/status/) has both sets of marks. ![The settings screen with the theme picker and a strip of palette swatches beside the theme name.](/assets/screenshot-settings.png) _Fig. 5s · settings_ ## Right-to-left text Hebrew and Arabic rows are painted as the cells they occupy, the same on every host. A terminal that runs its own bidirectional layout, iTerm2's right-to-left support or WezTerm's `bidi_enabled`, reorders those rows itself; turn that support off to read the frame in the columns Agent Manager paints. ## State Settings, order, groups, archive, the sessions layout and the split ratio live in `state.db`, and are restored on the next run.