---
title: "Configuration"
description: "The config file, the [tools.<name>] block, status and revive fields, themes, and where state is kept."
canonical: "https://agent-manager.dev/docs/config/"
last-updated: "2026-09-14"
section: "Documentation"
source: "agent-manager"
---

# Configuration

Config lives in your OS user config directory and is written on the first run with working defaults for Claude Code, OpenCode, Codex, Grok Build, Gemini CLI, Pi, Command Code and Hermes Agent.

| Platform | Path |
| --- | --- |
| Linux | `~/.config/agent-manager/config.toml`, or under `$XDG_CONFIG_HOME` when that is set. |
| macOS | `~/Library/Application Support/agent-manager/config.toml` |

Top-level keys: `poll_interval` (default `"2s"`) sets how often panes are polled for status, preview and stats. `editor` is the command `o` opens a directory in, arguments included; left unset, Agent Manager falls back 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`.

The generated file also carries a `[tools.terminal]` block. That one is the shell `T` opens, not an agent CLI: an empty `command` leaves the pane on `$SHELL`. `shell = true` is what marks it.

## Adding a CLI

Any other CLI runs as a session immediately, and earns live status the moment you describe it:

`config.toml`

```toml
[tools.mytool]
command = "mytool"
default_status = "idle"
rules = [
  { state = "working", pattern = "esc to interrupt" },
  { state = "errored", pattern = "(?im)^\\s*error:" },
]
```

Rules match top-down against the visible pane text and the first match wins; `default_status` applies when nothing matches. [Add any agent](/docs/agents/) walks through writing one of these from a real pane capture, and how to publish it.

## Refining the status

| Field | What it does |
| --- | --- |
| activity_cutoff | Regex locating the tool's input box. Everything above it is turn content. |
| turn_end | A turn-summary line marking the turn as over. |
| busy_line | Work that outlives its turn, such as background agents and shells. |
| limit_line | A usage or rate-limit banner; the session is `errored`. |
| chrome_line | Interface furniture to ignore when reading the pane. |
| blocked_line | A line that means the agent is waiting on you. |
| trailing_note | Trailing output that should not count as activity. |
| status_source | `"claude-hooks"` takes the status from Claude Code hook events instead of the pane. See [Status](/docs/status/#hooks). |

> **Worked examples ship with it** The generated config's `claude` and `opencode` blocks use all of these, so the file itself is the reference.

## When a status reads wrong

A field your config leaves out is filled from the built-in defaults on every launch, and a tool missing from the file is added whole, so an older config picks up new capabilities. A field you do have is yours and stays: a block that already carries a `rules = [...]` array keeps that array even after a release ships better rules for that CLI. That is what you want for a block you tuned, and it is the first thing to check when a supported CLI sits on the wrong state.

Delete the `rules` array from that tool's block, or the whole `[tools.<name>]` block, and relaunch: it comes back on the current built-in rules. To read the pane the way the poller reads it, run `tmux -L agentmgr capture-pane -p -t am_<id>` and compare it with the patterns in your block. A CLI that changed its output in a new version is worth [an issue](https://github.com/YoanWai/agent-manager/issues/new/choose) with that pane text and the CLI's version, since the built-in rules then need updating for everyone.

## Revive and prompts

| Field | What it does |
| --- | --- |
| resume_by_id_command | Resumes one exact conversation, with `{id}` replaced by the session's captured agent id. |
| session_id_flag | Launches the tool under an id the manager mints, for example `--session-id`. |
| session_store | `"codex"`, `"opencode"`, `"gemini"` or `"hermes"`, to read back an id the tool minted itself. |
| revive_command | What `v` falls back to when no id is available, such as `claude --continue`. |
| fork_command | Creates a conversation from an existing session. Claude Code, OpenCode, Codex, Grok Build, Gemini CLI and Pi include defaults. |
| prompt_flag | How the form's optional prompt enters the launch command. Empty for tools that take it positionally (`claude 'the prompt'`); OpenCode declares `--prompt`, since its positional argument is the project path. |
| prompt_mode | `"send"` waits until the input box appears, then submits the prompt there. Hermes uses this. |
| mcp | `"claude" \| "codex" \| "opencode" \| "grok" \| "gemini" \| "hermes" \| "none"`. See [MCP tools](/docs/mcp/#registration). |

## Themes

`s` opens settings, where `↑↓` move between fields and `←→` change the focused one. Fifteen palettes ship. Nine dark: classic, solarized dark, catppuccin mocha, tokyo night, gruvbox dark, nord, dracula, rosé pine and monochrome. Six light: solarized light, catppuccin latte, tokyo night day, gruvbox light, rosé pine dawn and paper.

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 matches the terminal's own background to the palette, so the window has no seam against it, and restores it on exit. Agent panes render on the theme's own backdrop, and the pane declares that background 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, to classic or solarized light. Your manual pick is kept separately, so turning the toggle off returns to it.

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

Order, groups, archive, theme and the split ratio live in `state.db`, a SQLite file next to the config, and are restored on the next run.