Reference
Protocol
Clients talk to a conch server with newline-delimited JSON over a stream: a unix socket locally, an ssh bridge remotely. This page describes the messages and where the code lives.
Messages
One JSON object per line. Requests {"id","method","params"} get {"id","result"} or {"id","error":{"code","message"}}; requests without an id are notifications.
Events
The server pushes {"event","data"}:
| Event | Carries |
|---|---|
pane.created | a new pane |
pane.exited | a pane whose program exited |
pane.closed | a closed pane |
pane.updated | a pane whose agent status, title or name changed |
pane.frame | a rendered snapshot of the screen, for subscribed panes |
project.updated | a project that was added or whose git state changed |
project.removed | a removed project |
agent.limits (a report carries every window the agent named in windows, beside the five_hour, week and spend an older build knows, so a per-model allowance is passed on rather than dropped) | plan limits that changed |
Bridge and hello
Over SSH the same stream runs through conch bridge. hello returns the server's version, build, platform, hostname, home and capabilities; clients use capabilities to detect servers from older builds. started is when the server first started and survives reloads; loaded_at is when the running build started, so a client can tell a reload has finished.
Methods
| Group | Methods |
|---|---|
| Server | hello, ping, server.stop, server.reload |
| Panes | pane.list, pane.create, pane.close, pane.resize, pane.send_text, pane.send_keys, pane.send_mouse, pane.scroll, pane.read, pane.rename, pane.subscribe, pane.unsubscribe, pane.mark_seen; pane.search finds text in a pane's history (capability pane.search.v1); pane.monitor watches a pane for output or silence, reported as monitor and alert in its info (capability pane.monitor.v1) |
| Agents | agent.report, agent.explain, agent.status, agent.install, agent.setup, agent.setup.sync, agent.limits, agent.broadcast; agent.setup.sync with user gives the other agents the setup in your home rather than a checkout's, and undo puts it back (capability agent.setup.sync.user.v1); agent.library and agent.library.apply keep MCP servers and skills in conch and write them where each agent looks for them (capability agent.library.v1); agent.prompt submits one message to an agent and answers with the turn that will reply, refusing an agent waiting for an answer with the code agent_blocked — turn in an agent's status counts its starts of work (capability agent.prompt.v1); agent.skill installs or removes conch's skill for the agents (capability agent.skill.v1) |
| Scoping | a pane's created_by names the pane it was started from, and a change asked from inside an agent's pane to a pane or project that isn't its own comes back with the code out_of_scope (capability pane.scope.v1); pane.caller says which pane a connection comes from and, for an agent, the name it goes by elsewhere, and scope.act_for holds a connection to what that agent started on this machine (capability scope.remote.v1) |
| Projects | project.list, project.add, project.remove, project.refresh, project.changes, project.diff, project.create, project.set_files, project.resolve (which project and branch a directory is in; capability project.resolve.v1) |
| Worktrees and tasks | worktree.add, worktree.remove, worktree.copy_files, task.create; a task's name names its pane (capability task.name.v1) |
| Branches | branch.commit, branch.push, branch.pr, branch.merge, branch.discard (capability branch.harvest.v1; a commit's patch field needs branch.hunks.v1, a push's rebase field branch.push.rebase.v1, and a push the remote is ahead of comes back with the code push_rejected, and a rebase undone by conflicts with rebase_conflict); branch.git runs the git panel's commands in the branch's worktree and reports an unfinished rebase or merge (capability branch.git.v1) |
| Worktree cleanup | worktree.stale, worktree.cleanup (capability worktree.cleanup.v1) |
| Moving a worktree | worktree.describe, worktree.pack, worktree.pack_read on the machine it leaves; worktree.have, fs.upload, worktree.unpack and project.clone on the one it goes to (capability worktree.move.v1). The servers never talk to each other: the client carries the pack |
| Sessions | session.list, session.search, session.resume, session.share, session.delete, session.dismiss; session.export and session.share with a doc hand a conversation to another machine (capability session.handoff.v1) |
| Files and shell | fs.list, fs.mkdir, fs.upload, shell.themes; fs.list with a root lists a project's checkout — files too with files, each with its size, time and git status — and refuses any path that leaves it (capability fs.files.v1); fs.read returns the first 256 KB of a file in a checkout, or says it is binary (capability fs.read.v1). With fs.transfer.v1, fs.list with files and fs.read without a root reach anywhere on the machine, fs.upload takes dir, archive (a packed folder), replace and mode, and fs.download / fs.download_read bring a file or folder back a chunk at a time. Either way a client keeps several chunks in flight: an upload that says parallel on its first chunk gives each one's offset, and the last chunk, which ends the copy, is sent or read only once every other one is answered. With fs.ssh.v1, a pane's ssh is the host its foreground ssh is logged in to, and fs.list, fs.read, fs.mkdir, fs.upload and fs.download take ssh, a pane, to work on that host's files instead — through sftp, made by the server with the pane's own ssh options and BatchMode=yes. With pane.ssh.v1, pane.create takes ssh too, and its command then runs on that host, through ssh -t with the pane's options, in a terminal beside it. An agent's connection reaches only the ssh hosts of panes in its scope |
Source layout
cmd/conch CLI entry point and subcommands
internal/proto NDJSON protocol: requests, responses, events, handshake
internal/server daemon: panes, projects and git refresh, unix socket
internal/client socket client, server auto-start
internal/pane PTY + VT emulator per pane, keys, mouse, title scanning
internal/detect agent detection: foreground process, screen manifests, state tracker
internal/adapter agent launchers with conch's integration wired in, title cleanup
internal/agentsetup what an agent loads in a folder: instructions, skills, MCP servers, plugins,
and writing one agent's instructions, skills and servers for the others
internal/sessions saved agent conversations, for listing and resuming
internal/usage token usage totals from an agent session's transcript
internal/brain the brain: request plans and agent summaries behind a Provider
internal/gitx git plumbing: worktrees, branches, status, changes, diffs
internal/ghx pull requests via the gh CLI
internal/remote ssh machines: probe, install, bridge, machine catalog
internal/update finds newer builds and applies them without stopping panes
internal/buildinfo build identity for comparing binaries across machines
internal/tui Bubble Tea UI: tree, changes view, overlays, mouse
internal/config paths and config.toml