Getting started

Introduction

conch is a terminal orchestrator for AI coding agents. A background server owns the terminals your agents run in, so they keep working when you close the UI.

Is conch for you?

conch is for running several coding agents at once and keeping track of them. If you have three or four going — on different branches, worktrees or machines — and the hard part is knowing which one is waiting on you, what each has changed, and getting back to it after your laptop slept, that is what this is. It assumes you live in a terminal, that you want work to survive the UI closing, and that you want to answer an agent's question from wherever you are, including a phone.

It is the wrong shape for several things, and here is what to use instead.

• One agent, one repo, no branches. conch adds a server, a tree and a key map you do not need. Run the agent's own CLI; add tmux if you want it to survive a dropped ssh session. conch earns its keep from the third agent, not the first.
• You handle git by hand. Tasks, worktrees per branch and the harvest flow are most of conch. If you would rather branch and commit yourself, a plain multiplexer — tmux, zellij, Zellij's floating panes — gives you the panes without the opinions.
• Review is your bottleneck. conch reads diffs properly now — side by side on a wide terminal, with what changed inside a line picked out, single hunks staged for a commit, and e to open the file at the hunk in your editor. What it still has none of: review threads with other people (comments in conch are for the agent — written on a hunk or a line, kept by the server, and sent to it as one message), approving a pull request, a three-way editor for a merge conflict (conch merges and, when that conflicts, hands it to an agent or to the git window), or a diff between two arbitrary commits. If those are your day, that is gh, your forge's web UI, or a graphical tool, and conch is the thing beside it rather than the thing it replaces.
• You want a desktop app. conch is a TUI. The phone app is a companion for answering agents away from the laptop, not a second home; there is no window with panels and menus, and there is not going to be.
• Windows. conch does not build for Windows — it is macOS and Linux, and it uses unix sockets and pty internals that have no Windows equivalent here. WSL works, and is the supported answer.
• An agent conch does not support in full. Five are supported — adapter, detection, sessions that list and resume. Others run here from a manifest: conch starts and watches them and does not read their saved conversations. If what you need is deep support for a sixth agent, say so rather than assuming the manifest covers it.
• Unattended swarms. conch waits for Enter on purpose: the brain proposes actions and nothing runs until you confirm, and an agent's question stops the work until somebody answers it. If you want dozens of agents running without a person in the loop, conch is deliberately not that, and will not become it.

The shortest version: conch is a terminal multiplexer that understands agents and git branches. Where it is the wrong tool, it is usually because you want fewer agents, a graphical diff, or no human in the loop.

How it fits together

conch has two parts:

• The server. Each machine runs one conch server. It owns every pane — the pseudo-terminals your agents and shells run in — along with their screens, scrollback and agent states. It starts on its own the first time you run conch.
• The TUI. Running conch opens a client that connects to the server. Press q to detach: the TUI exits, and the server and everything in it keep running. Run conch again to pick up where you left off.

Because the server owns the panes, you can close your terminal, lose your ssh session or update conch without stopping an agent. The server on a remote machine keeps working when your laptop sleeps, and the TUI connects to every machine at once.

The TUI is not the only client. conch web is another: it serves the same agents to a phone over your own tailnet, so you can see what each one is doing and answer the question it is waiting on from somewhere else. Nothing goes through a service of conch's; the phone reaches your laptop directly.

The tree

The TUI organises everything as a tree beside a live view of whatever you select:

MACHINES
▾ ● local                        ⠋1 ⚑1
  ▾ ▤ Workspace                      1
    ▾ ◆ api                      ⠋1 ⚑1
      ▾ Branches                     7
          ● main                    +1
          ◇ conch/add-health-check  ⠋ ↑3
      ▾ Agents                       2
          ⠋ Add health check   conch/add-health-check
          ! Fix flaky tests    fix/flaky
      ▾ Terminals                    1
          › dev-server         main
  ▾ ❯ CLI                          1
    ▾ Terminals                    1
        › zsh

• Machines — your own computer (local) and any machines you add over ssh.
• Workspace — a machine's projects, grouped together.
• Projects — git repositories (or plain folders) on a machine.
• Branches — with uncommitted changes, commits ahead and behind, pull requests, and the agents working on them.
• Agents and Terminals — the panes running in the project.
• CLI — a machine's own agents and terminals, started outside any project.
• Sessions — conversations agents saved, ready to resume.

See The interface for every detail of the tree.

Agent states at a glance

! jumps to the next agent waiting for you, and a desktop notification fires when one you aren't viewing needs you. Agents explains how conch decides a state.

Supported agents

• Claude Code
• Codex
• Gemini CLI
• OpenCode

conch can install any of them for your user, on any machine, without root. See Agents.

Where to go next

• Installation — install conch and keep it up to date.
• Quick start — from an empty terminal to agents working in parallel.
• Tasks and worktrees — one branch and worktree per task.
• Remote machines — run agents on other machines over ssh.
• Brain — ask for work in plain words and approve the plan.
• Keys and mouse and Command line — the reference.