---
title: "Add any agent"
description: "Turn any coding CLI into a managed session with live status: read its pane, write the rules, publish the profile under the agent-manager-tool topic."
canonical: "https://agent-manager.dev/docs/agents/"
last-updated: "2026-08-31"
section: "Documentation"
source: "agent-manager"
---

# Add any agent

Eight agents ship with working status out of the box. Every other coding CLI becomes a managed session the moment you describe it in one TOML block, and the description is short because the manager reads the same screen you do.

## The smallest profile that works

A name and a command are enough to make the tool appear in the new-session form and run as a real tmux session:

`config.toml`

```toml
[tools.mytool]
command = "mytool"
```

What it will not do yet is carry a colour. Without rules every session reads `idle`, which is `default_status`' fallback. The rest of this page is how to earn the other three states.

## Read the pane the manager reads

Status is not an integration. It is a handful of regexes over the text tmux hands back, so the first step is to look at that text yourself. Start the tool in a scratch session and capture it:

```bash
tmux new-session -d -s probe -x 120 -y 40 mytool
tmux capture-pane -p -t probe
```

That output, minus its colour codes, is exactly what the rules match against. Capture it four times: sitting at the prompt, mid-turn, on a permission dialog, and after an error. Those four captures contain every string a profile needs.

## The four states

| State | What to look for in the capture |
| --- | --- |
| working | The spinner or timer row a turn prints while it runs, and the interrupt hint beside it. |
| waiting | The selected row of an approval dialog, a trust prompt, or a confirmation hint. |
| errored | The tool's error prefix, usually a glyph or a leading `error:`. |
| idle | Nothing. It is the fallback when no rule matches and the turn has closed. |

Rules match top-down and the first one wins, so order them by specificity: the narrow dialog patterns above the broad spinner ones.

> **Two fields carry most of the accuracy** `activity_cutoff` is the regex for the tool's input box, which splits the turn's content from the furniture below it, and `turn_end` is the summary line a finished turn leaves behind. With both, a turn that ends quietly still resolves correctly. See [Configuration](/docs/config/#status-fields) for the full field list.

## A worked example

The shipped Gemini CLI block is a profile written exactly this way, and every regex in it traces back to a line in a capture:

`config.toml`

```toml
[tools.gemini]
command = "gemini"
default_status = "idle"
activity_cutoff = "(?m)^\\s*[>!*] "
rules = [
  { state = "waiting", pattern = "(?m)^[\\s│]*●\\s*\\d+\\." },
  { state = "waiting", pattern = "Waiting for user confirmation" },
  { state = "working", pattern = "esc to cancel" },
  { state = "errored", pattern = "^✕ " },
]
```

| Line in the pane | What it became |
| --- | --- |
| The composer, `>` normally and `!` in shell mode | `activity_cutoff` |
| `│ ● 1. Allow once`, the selected row of an approval box | the first `waiting` rule |
| `(esc to cancel, 12s)`, the running turn's status line | the `working` rule |
| `✕`, the error prefix | the `errored` rule |

Six lines of regex for a tool the manager knows nothing else about. Revive, prompts and MCP registration are separate fields, each optional, each documented on the [Configuration](/docs/config/#revive) page.

## Publish the profile

A profile that works is worth more to the next person than it is sitting in your own config. Put it in a repository as `profile.toml` with a README showing the tool's version and a capture or two, then add the topic `agent-manager-tool` to that repository.

```bash
gh repo edit --add-topic agent-manager-tool
```

Every repository carrying that topic is listed at [github.com/topics/agent-manager-tool](https://github.com/topics/agent-manager-tool), so a profile becomes discoverable without a registry, a pull request or a review queue. Installing one is a copy into `config.toml`.