Reference

Command line

Everything the TUI does to panes, projects and machines is also a conch subcommand, so you can script agents from a shell. conch help prints the commands to start with, and conch help all every one.

Scripting

conch task -cwd ~/src/api "Add a health check endpoint"   # pane, worktree, branch
conch new -agent claude -cwd ~/src/api                   # Claude in the repo
conch send p1 "fix the failing tests" && conch send -keys p1 enter
conch read p1                          # visible screen as text
conch status                           # panes with agent state
conch project ls                       # projects, base, worktrees
conch branch commit -m "Fix the flaky test" && conch branch pr   # finish a task
conch worktree clean -y                # remove finished worktrees and their branches
conch wait p1 && conch send p2 "review what p1 just changed"   # chain tasks
conch agent prompt -wait p2 "check finding 3 again" && conch read p2   # one agent driving another
conch close p1
conch server reload                    # run a new build; panes keep running
conch server stop                      # stops the server and all panes

On macOS the server runs with GODEBUG=asyncpreemptoff=1, restarting itself once at start-up to get there: a reload re-execs the server process, and macOS makes that wait for scheduling signals a busy server never takes, which would leave it serving nothing. If a reload ever leaves the socket in place with nothing serving it, conch status says the server is not answering rather than that it is gone, and simply running conch again clears that socket and starts a fresh server. The panes of the old one are lost; nothing else needs cleaning up by hand.

Global flag

-m MACHINE (or --machine MACHINE) before the subcommand runs it against a remote machine instead of this one; local means this machine.

conch -m gpu-box status

Subcommands

conch

conch with no subcommand opens the TUI, starting the server if needed.

Inside one of its own panes it refuses, the way tmux refuses a nested session: the inner TUI would take the keys and the mouse, and closing the pane would kill it. Detach with ctrl+b d first, or run CONCH_PANE_ID= conch to open one inside the pane anyway (conch -m MACHINE for another machine's TUI always works).

server

Panes

Pane names

Every command that takes a pane's ID — send, read, close, redraw, wait, rename, agent explain, agent prompt — takes its name as well: the one in conch status's name column, set with conch rename or conch task -name. That is how one agent addresses another it started, without keeping track of IDs:

conch task -name reviewer -agent codex "Review the diff on this branch"
conch agent prompt -wait reviewer "Check finding 3 again" && conch read reviewer

• An ID is always an ID: p and a number is never looked up as a name, so names of that shape are refused.
• A name is looked up once, when the command starts; a wait then stays with that pane.
• Names are exact and case sensitive. A name two running panes share is refused rather than guessed — say which with its ID. A pane that has ended still answers to its name until another running pane takes it.
• Names belong to one machine's server, so -m looks them up there.

When an agent runs these commands

An agent in a conch pane can drive conch with the same commands — start a reviewer, prompt it, read its answer. conch agent skill -apply teaches it how, and when to stop and ask you; Agents working together walks through it with examples. What it may change is kept to its own work:

• panes it started, and the panes those started, in any project;
• panes in its own project, whoever started them;
• its own project's branches and worktrees.

Anything else — typing into, closing, renaming or marking as seen another project's pane, sending it keys or a broadcast, removing another project, committing, pushing or discarding there — is refused with out_of_scope, and so is conch server stop or reload, and changing your own setup: the agents' skill, the library, a sync, or which local files a project copies into its worktrees:

conch: out_of_scope: the claude agent in p4 may not close p1: it did not start it, and it is in another project; do it from the TUI or a terminal pane

Reading is never refused (read, status, wait, sessions), and neither is starting panes and tasks: what an agent starts is its own, and each pane in the server's pane list carries who started it (created_by).

conch tells who is asking from the operating system — the process at the other end of the socket, and its parents up to a pane — not from CONCH_PANE_ID, so unsetting that changes nothing. Only a pane with an agent running in it is held to this: a terminal pane, the TUI and scripts outside conch act as you. It is a guard against a confused agent closing the wrong session, not a sandbox: a program set on escaping can leave the pane's process tree.

On other machines. -m from an agent's pane carries its scope along: conch asks this machine's server who is running the command and, for an agent, has the other machine's server hold the connection to what that agent started there — its panes (and theirs), and the projects it started them in. It has no project there otherwise, so another project's panes stay out of reach even when they share a name with its own. A machine whose conch predates this isn't driven from an agent's pane at all; conch machine upgrade it. A terminal pane's -m is you, as before. Like the rest, this asks conch: an agent that runs ssh itself, or points CONCH_SOCKET elsewhere so this machine's server can't be asked, is not held by it.

agent

project

task

conch task [-cwd DIR] [-branch B] [-base B] [-agent NAME] [-n N] [-name N] [-at TIME] [-every SPAN] [-queue [-wip N]] [-after REF] PROMPT creates a branch and worktree and starts an agent with the prompt (-at later, -every again and again, -queue when the project has room, -after once other work has finished, on top of it: see Later, and on a schedule; conch schedule lists and removes what is scheduled); in a folder that isn't a git repository — or, with -m and no -cwd, the machine's home — the agent works there with no branch. See Tasks.

branch

Finishing a task from a script, the same steps as the changes view. Every command takes -cwd DIR (a directory in the project; default: the current one) and -branch B; without -branch conch uses the branch checked out in that directory. With -m MACHINE, -cwd is required and must be an absolute path on that machine.

conch branch commit -m "Add the health check" && conch branch pr -title "Health check"
conch branch merge && conch branch discard      # land it and clean up

review

The changes view's comments from a shell: the same ones, kept by the server, so a comment written here shows on a's hunk marks and the phone's agent card, and the other way round. Like branch, every command takes -cwd DIR and -branch B, and without -branch uses the branch checked out in that directory.

conch review add api/login.py:42 "This swallows the timeout; let it raise."
conch review send

An agent kept to its own work may comment on and send for its own project's branches, and no others — which is what lets a reviewer you started leave its findings as comments instead of a file.

worktree

Committing single hunks is a TUI-only step: see Finishing a task.

machine

sandbox

ID is the machine's ID or label, the provider's own sandbox ID, or PROVIDER:ID; it must belong to the provider -provider names. See Sandboxes.

web

conch web [-listen ADDR] [-port N] [-url URL] [-cert FILE -key FILE]   # the gateway a phone reaches
conch web pair [-permission view|reply|full] [-machine NAME]  # a QR code and one-time code, good for 5
                                                            # minutes; it reaches this computer unless
                                                            # -machine names a machine
conch web devices                                           # the paired phones
conch web revoke ID                                         # cut one off at once
conch web permission ID view|reply|full [-machine NAME]...  # change what one may do, and which
                                                            # machines it reaches (this computer only
                                                            # until you name one; 'local' clears them)
conch web stop                                              # end one running in the background

conch web serves your phone on this machine's Tailscale address and nowhere else, unless -listen names another address. -url is the address phones open — the https://…ts.net one tailscale serve gives — which the QR code points at. pair draws the QR code only when it prints to a terminal. It takes no -m: it shows the agents of the machine it runs on. pair and revoke are refused from an agent's pane.

mcp

conch mcp                                                   # an MCP server on stdin and stdout

An agent that would rather call a tool than a command talks to conch through conch mcp: a Model Context Protocol server over stdio, in front of the same socket the CLI uses. A tool call comes back as a typed result and a refusal it can act on, where shelling out hands it a screenful of text to parse.

view and show are the two that reach past the server to the screen. The server owns panes and the terminal owns the arrangement of them, so conch carries both ways: a TUI publishes what it is showing, and a show is passed back to it as a request. A request, not an order — the panes asked for are gathered side by side in one tab and nothing else is touched. They move rather than being copied, since a pane is shown in exactly one place, which is the same rule that governs ctrl+b ! and dragging a pane between tabs. An agent may only show panes it could already type into, by the same scope that governs prompt.

The tools are the same work as conch agent prompt, conch wait, conch task and the rest — the same server methods with the same payloads — so the two doors cannot drift. Scope comes for free: conch finds the caller from the socket's peer pid walked up to a pane's program, so an MCP server an agent starts inside its own pane reaches only what that pane may reach, and nothing in a tool call can widen it.

Installing it is one action, because the entry is the same for every agent — the library writes it in each one's own format:

conch agent library mcp          # conch's own tools, as a server in the library
conch agent library apply        # write it into each agent's configuration

Or in the TUI: , → Agents → Shared MCP servers & skills… → Add conch's own tools…, then Apply…. It is conch mcp on stdio with nothing in its environment — it finds its socket the way every other command does — and the command is the bare name, so an update that moves the binary doesn't strand it. Adding it twice is adding it once. Restart an agent afterwards for its client to list the tools.

Three reviewers at once is what this is for: several helpers, several kinds of agent, no shell.

Stdin and stdout are the protocol: notes go to stderr, one request per line (this revision of MCP has no batches), answered one at a time in order, and a wait tool holds the session until it ends, as conch wait holds a shell. A tool that names a pane refuses a name shaped like a pane id or one another running pane holds, as conch rename does — ids win, so such a name would pick out nothing. timeout_seconds defaults to 1800, 0 waits with no limit, and anything over a day is capped.

doctor

conch doctor          # check what conch needs, and say how to fix what is wrong
conch doctor -json    # the same checks, for a script

The first thing to run when something does not work. Each line is one thing conch relies on, and anything wrong comes with the command that puts it right:

✓ conch     0.1.9 · darwin/arm64
✓ config    /Users/you/.config/conch/config.toml
✓ socket    /Users/you/.config/conch/conch.sock
! server    pid 28356, up 6d, on another build (0.1.8) than this conch (0.1.9)
            → conch server reload -binary /Users/you/.local/bin/conch  (panes and agents keep running)
✓ agents    claude 2.1.3 · codex 0.46.0  (not installed: gemini, opencode, devin)
✓ git       2.49.0, committing as You
! gh        2.62.0 not signed in
            → gh auth login
✓ terminal  ghostty, xterm-256color, 24-bit colour
✓ machines  1 machine saved (not dialled; conch -m NAME status reaches one)

conch works; 2 things worth a look.

It exits 1 when anything is marked ✗, and 0 otherwise. The checks run side by side, so one slow thing costs only its own wait. It changes nothing and starts nothing — not even the server — and it does not dial your machines, so a machine that is asleep cannot make it hang. Whether gh is signed in is asked without reaching GitHub, so an offline laptop is not called signed out (a gh too old for that is asked the usual way), and the token gh hands back is thrown away. It checks this computer: on another machine, run it there.

bug

conch bug                                                   # the facts about this conch
conch bug -open "the tree lost a terminal"                  # …in a GitHub issue, already filled in
conch bug -log                                              # where the server's log is

What to hand over when conch itself is the problem, without writing anything down:

conch 0.1.7-dev (build 29945acfb71a, darwin/arm64)
server: 0.1.7-dev (build 01096cd11ad4, darwin/arm64), pid 28356, up 6d
  reloaded 5h06m ago
panes: 25 · claude×16
machines: 2, 1 reachable
terminal: iTerm.app, xterm-256color, 247×48, icons=nerd
last error: out_of_scope: the claude agent in p1 may not reload the server

It is facts, not contents: versions, counts, sizes, the capabilities a server is missing, and conch's own last error. Never a path, a project, a branch, a pane's title or anything off a screen — which is what makes it safe to send without reading it through first. The two builds above being different is the sort of thing it is for.

-open opens a GitHub issue with the block already in it; nothing is sent until you press submit there. Over ssh, or anywhere with no desktop, it prints the link instead. -log says where the server's log is and what is in it — paths, branch names and pane titles — and leaves attaching it to you.

Run conch doctor first: what it finds usually has a fix you can make yourself.

In the TUI the same thing is , → Report a problem…, which shows the report and offers to open the issue, copy it, or copy the log's path.

ask

conch ask [-y | -n] REQUEST asks the brain; it proposes actions and runs them once you confirm. -y runs the plan without asking; -n only shows it.

update

conch update [VERSION | latest | list | rollback] replaces this binary with a release and reloads the local server onto it, keeping panes.

See Auto-update and Going back to an older version.

version

conch version [--json] prints the version, build and platform (also --version, -v).

Internal commands

These are run by conch itself, not by you: