Using conch

Brain

The brain turns a request in plain words into a plan of conch actions — start tasks, message agents, answer questions — and summarises what agents are doing. It uses your own agent login or API key.

Asking

Press : (or click ✦ Ask) and say what you want:

• "start 3 agents on api: fix the flaky login test, add rate limiting, update the README" — split into tasks, each on its own branch and worktree with a self-contained prompt
• "tell the agent on fix-login to also cover the logout path" — a message typed into that agent
• "hand the auth thread to Codex" — the Claude conversation in that pane is written to a handoff file and Codex is started on it, as s does in Sessions
• "tell every agent in api to run the tests" — one message to several agents at once, as B does in the tree
• "what is waiting for me?" — an answer, no actions

From a shell, conch ask [-y | -n] "…" does the same: -y runs the plan without asking, -n only shows it.

Approving the plan

The brain sees every connected machine, its projects, branches and agents (with their states and summaries) and proposes a plan. Each action is listed with a checkbox; invalid ones (an unknown project, an agent that isn't installed, an offline machine) are marked and skipped.

It can propose these actions:

A broadcast and a share only ever reach agents: a terminal would run the text as a shell command, so conch skips it and says so. Sharing needs the agent to have saved a conversation; until it has, the action is refused rather than starting an agent with nothing to read.

Handing work to another agent

Say who should take over, and from where:

• "hand the auth thread to Codex"
• "let Gemini continue what Claude is doing on fix-login"
• "give the drag-and-drop thread to the Codex that is already running"

✦ Plan
  1. Hand the conversation of fix login on this computer to codex (a new pane)
  enter run · space tick · esc cancel

On enter, conch writes that agent's conversation to a handoff file in the checkout and starts the other agent on it with a prompt to read it and continue — the same handoff as s in Sessions. Name an agent that is already running and the conversation goes to it instead of starting a pane.

One message to several agents

• "tell every agent in api to run the tests before committing"
• "ask both agents on conch to stop and summarise what they changed"

✦ Plan
  1. Send to 2 agents on this computer (fix login, codex): run the tests before committing

Each agent receives it once, submitted as its next message, like B in the tree. Agents on several machines take one action per machine, each confirmed on its own.

Finding what needs you

/ then ! keeps only the agents waiting for an answer, on every machine, without asking the model anything:

/ !  agents waiting for you
▾ ● local                          ⠋1 ⚑3
  ▾ ◆ api                          ⠋1 ⚑2
    ▾ Agents                           3
        ! claude                    feat
        ✓ gemini                    done

esc clears it; ! on its own jumps to the next waiting agent instead of filtering.

Summaries

S on an agent asks for a one-line summary — what it is doing and what it needs from you — shown in its title bar and on the project page, and given to the planner.

Settings → Brain → Summarise agents does this on its own whenever an agent finishes or starts waiting.

Providers

Choose a provider in Settings → Brain, or with [brain] in config.toml:

Configuration

[brain]
provider = "claude"
model = ""            # provider default
summary_model = ""    # a small, fast model by default
summaries = false     # automatic summaries

Three more keys are optional:

New providers

New providers implement brain.Provider (Complete with an optional JSON schema for structured output).