Using conch

Agents

conch runs Claude Code, Codex, Gemini CLI, OpenCode and Devin in panes it owns, tracks what each is doing, and shows their token usage and plan limits. It wires in its state tracking without touching the agents' own configuration.

Two tiers, said plainly

conch supports five agents and runs more. The difference is a promise, not a ranking:

• Supported — an adapter written for it, detection rules taken from the real agent, and its saved conversations listed, resumed and deleted in the Sessions view. Claude Code, Codex, Gemini CLI, OpenCode and Devin.
• Runs here — described by a manifest: conch starts it, recognises it in a pane, and gives it a first message or resumes it only where that agent documents how. Its saved conversations are not read, and conch says so — in the agent menu ("runs here · no sessions") and in the Sessions view — rather than showing an empty list that reads as "you have not used it".

Pi is the one that needs no rules at all: it reports its own state through OSC 7501, so its row in the tree says what pi says — working, waiting, done — where another second-tier agent can only be shown as idle until conch is taught its screen. Any agent that adopts the protocol gets the same, including one you add yourself.

The second tier exists because the wider catalogs detect twenty agents while conch supports five, and writing fifteen more to the supported bar stalls on session formats nobody has written down. Running an agent is easy; pretending to read its sessions is a lie.

conch ships manifests for Aider, Amp, Cursor CLI, Grok, Kilo Code and Pi, each saying in its own file what was verified from that agent's documentation and what was not — these are other people's flags, and they change. Add your own with:

conch agent add robo -command robo -label "Robo Coder" \
  -prompt '--message {prompt}' -resume '--resume {id}' -resume-last --continue

That writes ~/.config/conch/agents/robo.toml, which you can then edit by hand; reload the server to pick it up. Leave -prompt out and conch will not try to give it a first message; leave -resume out and it will not offer to resume one. Add an install line to its [run] table for an installer conch can offer; without one the agent menu says conch has none rather than running nothing and calling it installed. A manifest cannot take a supported agent's name — that would replace a tested adapter with a guess.

An agent conch runs from a manifest is marked in the tree like any other — a square rather than a circle (see the sidebar), and 🤖 for one conch has no mark of its own for.

Supported agents

Devin for Terminal is Cognition's devin CLI, not the Devin desktop app. conch starts, resumes and installs it like the other agents, and lists it in c. Its instructions, skills and MCP servers show in the setup view (i) and take part in sync and the library; since it reads Claude Code's files by itself, it is only given what it would not otherwise see.

conch reads working from its screen, so the tree shows the spinner while it thinks or edits, and it catches the trust prompt Devin shows on its first run in a directory. It cannot show waiting the rest of the time: Devin asks for permission in prose in the conversation — "This will permanently delete the file. Should I proceed?" — leaving the input placeholder and status bar exactly as they are when it is idle, and its terminal title is only the session's first prompt. So a Devin pane that needs an answer looks idle, and ! will not jump to it. Hooks would fix that; conch only adds them once it's confirmed that passing --config leaves your own Devin settings intact.

Starting agents

c (or clicking c agent in the status bar, or Start an agent… in the right-click menu) asks which agent to start at the selected place — a machine, project, branch or pane. Every agent installed there is listed first, in the machine's own order, with what would have to be installed after it; the default (Settings → Agents) is pre-selected, so c enter starts it. The first ten rows that do something take a digit — 1–9 and then 0, as the tab keys do — so the agents you are choosing between keep the numbers even when a dozen are listed. Missing agents can be installed from the same list; A starts or installs any agent.

Opening the menu asks the machine again which agents are there, so one you installed since conch started — by hand, or with brew, npm or its own installer — is offered as a start rather than an install; if the answer arrives while the menu is open, the menu redraws. An agent whose manifest named no installer is listed as "not installed · conch has no installer for it" and cannot be chosen: install it yourself and conch will find it on your PATH.

t tasks use the default agent unless the task dialog's Agent field (or conch task -agent NAME) names another. From a shell, conch new -agent claude -cwd DIR starts Claude Code with state tracking, and conch agent status / conch agent install NAME check or install agents (add -m MACHINE for a remote machine).

Agent states

A desktop notification fires when an agent you aren't viewing needs you (see notification settings). ! in the tree, or ctrl+b ! in a pane, jumps to the next agent waiting for you.

How the state is decided

Most reliable first:

1. The program's own report (OSC 7501). An agent that speaks the Program Status Protocol says what it is doing on the terminal it already has — idle, working, done, blocked (with permission, question or auth), error — and conch takes that over its own screen rules, because the program is not guessing. A program asks first whether the terminal speaks it, and conch answers; one that gets no answer stays quiet, so this works in conch and not in a terminal that has not implemented it. It travels down the pty, so it works over ssh and inside a container, where a hook or a socket would not. Claude Code 2.1.295 and later emit it, and so do a growing number of others. A blocked report outranks everything; otherwise hooks still come first for the agents that have them, since a hook also carries the message, whether the work failed and which session it belongs to.
2. Hooks. Claude panes started by conch get --settings ~/.config/conch/claude-settings.json, adding hooks that call conch report claude-hook. Your own settings files are untouched and their hooks still run. conch writes that file — and Gemini's defaults and OpenCode's plugin beside it — when its server starts and before every launch, so clearing ~/.config does not leave an agent failing with Settings file not found; the folder is made again if it has gone.
3. Screen rules. Regexes over the bottom of the screen (tolerant of line wrapping), e.g. "Do you want to proceed?" with its numbered choices under it → waiting; the question alone (typed, logged or quoted) is not. Also covers claude started by hand. Override internal/detect/manifests/claude.toml by copying it to ~/.config/conch/agents/claude.toml.
4. Foreground process. A pane is only an agent while the agent is the terminal's foreground process.

A report decides a pane's state, never whether it holds an agent: that still comes from the manifest and the foreground process, so a build tool reporting working in a terminal stays a terminal.

conch agent explain p1 shows the evidence behind a state.

conch reports its own state too

conch reads OSC 7501 because it is the terminal its agents run in. It is also a program on your terminal, with the same thing to say, so it emits one report of its own: blocked while any agent is waiting on you, error when one has failed, otherwise working, done or idle, with a line naming the agent when there is one of it (claude on feat waiting) and counting them when there are more. A terminal that understands the protocol can then put that on the tab or the window — which is the one state you cannot see for yourself, because seeing it means looking at conch. It counts every agent conch knows of, not only the workspace on screen, since the terminal's tab is outside workspaces and an agent waiting in one you switched away from is exactly the one that is out of sight. conch takes the report away when it quits, so no tab is left saying an agent waits after the conch that said so has gone.

Unlike an agent, conch does not ask the terminal whether it speaks the protocol first. The answer would arrive on conch's own stdin, where the TUI reads keys and would take ESC ] 7 5 0 1 ; for an escape followed by the digits 7, 5, 0, 1 — digits that switch tabs. Writing without listening is the safe half: never asking means nothing ever arrives to be misread. A terminal without support throws an unknown OSC away, and these are written only when something changes, so the cost of telling one that is not listening is a few bytes a minute. It is off inside tmux and screen, which own the window the report would reach, and CONCH_STATUS=0 turns it off anywhere (1 turns it on, tmux included).

Agents working together

An agent can start another — a reviewer for its change, a tester — prompt it and read its answer, kept to its own work while it does. See Agents working together.

Broadcast

B types one message into several panes at once and submits it. The brain can propose the same thing from a plain request, such as "tell every agent in api to run the tests". An agent gets it as its next message — "run the tests and fix anything you broke" to every agent in a project — and a terminal runs it as a command — git pull in every checkout.

What is listed follows the selection in the tree, grouped the same way (project or CLI, then Agents and Terminals):

What starts ticked:

• Agents — all of them, except agents waiting for an answer: the message would answer their question. You can tick them; the confirmation says so.
• Terminals — ticked when you selected a Terminals section or a terminal. In a mixed list they start unticked, since a prompt meant for agents would run as a command; t ticks them all.

In the dialog, type the message, then tab to the list: space ticks or unticks, a ticks all, t all terminals, e widens to every machine. enter shows the recipients and how many terminals will run it as a command, and asks to confirm; n goes back with the message kept.

Panes on other machines receive it through their own servers. A server from an older build is skipped and named (older servers can broadcast to agents but not terminals).

Token usage

Agent panes show token usage in their title — ctx 45k/200k · out 12k · $0.42:

• ctx — how much of the model's context window the conversation fills right now (the input of the latest request), out of the window's size when the agent reports it. When it nears the size, the agent compacts or forgets.
• out — output tokens the agent has generated in this session so far.
• $ — the session's cost, only when the agent reports one.

conch reads these from each agent's own session data and never estimates prices:

A machine's page totals the usage of its running agents.

Plan limits

For Claude subscriptions the status bar shows the current windows, e.g. Claude 5h 42% · 7d 18% (amber from 70%, red from 90%); click it for reset times. The machine page draws them as bars with when each window resets. When a window passes 80% and again at 95%, conch alerts once (see notification settings).

Claude shares these only with its status line, so conch adds a status line command to its --settings that records them and then runs your own status line unchanged. Codex's windows are read from its session files when its login has them. API-key logins have no plan windows.