Quick start

curl -fsSL https://raw.githubusercontent.com/Amitgb14/conch/master/install.sh | sh

This installs ~/.local/bin/conch, and says what to add to your shell if that folder isn't on your PATH. With Homebrew, brew install Amitgb14/conch/conch instead. See Installation for other ways.

If anything below does not work, conch doctor checks git, gh, your agents and your terminal, and says how to fix what it finds.

conch

The first run starts the conch server in the background. You see the tree on the left, with your computer as local, and a live view of the selection on the right. ? lists every key.

Until you have tried them, the page on the right also lists four steps under Getting started: add a project, give an agent a task, open the review queue, and detach. Each ticks itself off once you have done it, the list goes away once all four are, and x on local hides it sooner. The steps below go through them.

Select local and press a. A folder browser opens: enter opens a folder, ← goes up, / filters and g jumps to a typed path. Press a to add the selected folder, or . to add the folder you're in. p creates a new project instead — a folder with a git repository and an initial commit.

Projects also appear on their own when you open a pane inside a git repository. From a shell, conch project add PATH does the same.

With the project selected, press c. conch lists every agent installed on the machine with your default pre-selected, so c enter starts it in the project's folder. A missing agent can be installed from the same list.

The agent's pane opens on the right. Type into it as you would in any terminal; ctrl+b then any key returns to the tree.

Press t on the project and describe the work, for example "Add a health check endpoint". conch creates a branch named from the prompt, checks it out into <repo>.worktrees/<branch>, copies your local files such as .env into it, and starts the agent with the prompt. Start a few tasks: each is isolated from the others.

The same from a shell:

conch task -cwd ~/src/api "Add a health check endpoint"

See Tasks and worktrees.

Each agent shows its state in the tree: ⠋ working, ! waiting for you, ✓ done, ○ idle. Press ! (or ctrl+b ! from inside a pane) to jump to the next agent waiting for you, or click the count in the status bar. It keeps the two apart — ⚑ 1 waiting · 1 done — as the tree's badges do (⚑1 ✓1): waiting means the agent stopped to ask you something (a permission, a question) and does nothing until you answer; done means it finished while you weren't watching, and turns idle once you look at it or type into it.

To tell several agents the same thing — "run the tests and fix what you broke" — select the project and press B: pick who receives it and confirm.

A desktop notification fires when an agent you aren't viewing needs you. Press , to open Settings, where Notifications sets how you are told — desktop, sound, terminal beep — and quiet hours.

Select a task's branch to see its changes: its pull request (checks, review), uncommitted files, commits ahead and diffs. enter on a file shows its diff, o opens the branch's pull request and esc goes back. x on the branch removes its worktree once you're done (never with uncommitted changes).

Press q. The TUI exits, but the server keeps every agent running. Close the terminal, go for lunch, then run conch again: everything is where you left it, including agents that finished or started waiting meanwhile.

Press M, or from a shell:

conch machine add gpu-box   # an alias from ~/.ssh/config, user@host or ssh://user@host:port

conch probes the machine over ssh, installs itself there if needed and connects. The machine appears in the tree, and you add projects and start agents on it exactly as on local. See Remote machines.

Press : (or click ✦ Ask) and say what you want, for example "start 3 agents on api: fix the flaky login test, add rate limiting, update the README". conch proposes a plan with a checkbox for each action.

See Brain.