---
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-07"
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. 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/` |

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.

## 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.<name>]` 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 and Oh My Pi 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 and Oh My Pi 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.

## 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`) 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` and `quit`. 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, and `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 `↑↓` move between fields and `←→` change the focused one. Seventeen palettes ship. Ten dark: classic, solarized dark, catppuccin mocha, tokyo night, gruvbox dark, nord, dracula, rosé pine, monochrome and kanagawa wave. 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.

![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.