berth vs parallel-agent tooling — berth documentation

Start with the framing, because the comparison only makes sense inside it. These tools and berth operate at different layers of the same stack, so the useful question is not which one wins but which layer is missing on your machine. Nothing here describes how Conductor, Crystal, vibe-kanban or any other product is built; this page compares the design intent of a session-orchestration layer with the design intent of a workspace runtime, and every berth statement below is drawn from berth's own published documentation.

The axes

Design-axis comparison. The second column describes the axis an orchestration layer has to answer — a design question at that layer — rather than a claim about any specific product.
Design axis	berth	parallel-agent tooling
Primary unit of work	A workspace: one worktree, one branch, one private data directory, one reserved port set, one supervised process graph, addressable by slug	A session or a task as the layer defines it. Whether that maps onto exactly one checkout, and who owns that checkout, is the question this row raises
Interface	A CLI, with `--json` on every subcommand and an embedded agent skill that any harness able to run shell commands can read	Typically a human-facing surface — a list of sessions, diffs, review affordances — which is the layer's job, not a defect
Where it runs	On your machine, beside the repository: a local binary whose only hard dependency is Git	Wherever the layer is installed. That is a product decision, and this page does not assume one
Who creates and owns the per-task checkout	berth creates it (`berth new`) and owns it, or registers an existing linked worktree with `berth adopt`; an adopted checkout is never removed	The axis to check first: whatever creates the checkout defines its removal policy, and everything underneath inherits that decision
Port and data handling	Named ports reserved atomically with the workspace record and stable for its lifetime; private data in `$BERTH_DATA_DIR`; `copy_dirs` and `.worktreeinclude` seed dependencies and local files during setup	Undefined until something defines it. Two sessions that both start the server their project hardcodes will collide whichever interface started them
Process supervision	A declared process graph with readiness probes; `up`, `down`, `status` and `logs` per workspace; nothing depends on a window staying open	The question every session layer has to answer: when the session ends, what stops the servers it started?
Host tooling and editor integration	No editor of its own: `berth attach` prints the path, branch and shell exports, and `berth hook install` merges the Cursor worktree adapter	Where a session layer earns its place — triage, review and human control gathered into one surface
Scripting and harness coverage	Machine-readable output on every subcommand; the skill installs once into `.agents/skills/berth`, read by Cursor, Codex, pi and Antigravity, and berth writes nothing into a harness's own rules file	The axis that varies most, and the one worth asking about: can the layer be driven without its own user interface?

Two layers, not two competitors

An orchestration layer sits on top of a human's attention: it shows many sessions at once, gives each one a place in a queue, and puts a review step between the agent finishing and the result being accepted. A workspace runtime sits underneath: it makes sure each of those sessions actually has a directory, a branch, a database it does not share, a port nobody else is using, processes that stop when the session is over, and a removal path that cannot delete work nobody preserved. Both layers are real work, and neither is a worse version of the other.

What an orchestration layer gives you

The category's job is triage and control. When five agents are running, a human needs to see which sessions are progressing, which are blocked, which are waiting for review, and what each one changed — and needs to be able to stop one, redirect one, or take over the diff before it lands. That is an interface problem more than a runtime problem, and it is where a graphical, session-oriented tool is genuinely the better answer: a terminal plus five background processes does not give a reviewer a queue, a diff view or a place to approve.

What still has to exist underneath

Whichever layer you start sessions from, five things have to be true of the environment each session runs in, and none of them are solved by an interface: one real checkout per task, so two agents are not editing the same files; a port set that does not collide, so two dev servers can run at once; a data directory that does not corrupt, so two migrations are not applied to one database; supervised processes that stop when the task ends, instead of holding ports until the machine restarts; and a removal path that refuses to delete anything whose work was never preserved. Keep the review UI and the workspace runtime conceptually separate and it becomes obvious which one you are missing when something goes wrong.

What berth provides at the workspace layer

berth is deliberately the lower half. It is a CLI — no server, no daemon, no interface to keep open — whose primitives are exactly the five concerns above: berth new creates the checkout and reserves the ports, berth run executes a command in the same runtime and environment as the services, berth status reports readiness, berth logs shows a process, berth down stops the graph while keeping data, and berth done releases the workspace once the commit is preserved. Every subcommand takes --json, which is what makes berth scriptable from any harness rather than only from a person at a keyboard.

The agent-integration story follows the same principle: one skill, installed to .agents/skills/berth — the single location Cursor, Codex, pi and Antigravity all read — so any agent that can run shell commands can drive the workspace lifecycle without berth knowing anything about that harness. berth writes nothing into AGENTS.md, GEMINI.md or any harness's own rules file.

berth new feature-a --up        # checkout, reserved ports, supervised processes
berth run -- npm test           # same runtime and environment as the services
berth status --json             # readiness for scripts, not sleep loops
berth down feature-a            # stop the graph, keep the data
berth done feature-a            # release the workspace once the commit is preserved

This page makes no claims about any named tool's internals. Conductor, Crystal and vibe-kanban are named here only to identify the category this page compares against — a session layer with a human-facing review surface. Whether a given tool has a headless mode, which harnesses it drives, or how it provisions directories is something to read in that tool's own documentation.

What berth deliberately is not

berth has no GUI, no task board, no session queue and no human review UI, and it does not plan to grow them: an interface that shows many sessions is a different product with a different user. It also does not decide which agent runs, does not keep a conversation, and does not hold a queue of work. If you are looking for a place to watch six agents work, triage their output and approve diffs, berth is the wrong layer to evaluate — that is the session layer's job, and it is a real job.

Interoperability: checkouts you did not create

The layers do not have to be chosen exclusively, because a harness that hands you a Git worktree berth has never seen can be brought under management in place. Run berth adopt --setup inside that checkout when it is on a branch: berth registers it, applies the ports, data directory and process graph the workspace needs, and records it as adopted — which means it will never be removed implicitly, and berth done on it stops and unregisters the runtime while preserving the checkout, the data and the branch even with --force. When the harness creates a detached worktree, or the task needs its own ports and data, berth new is the right call instead. The Cursor worktree adapter installed by berth hook install does exactly this: it runs berth adopt --setup inside every worktree Cursor creates, so sessions started from that editor land on managed ground without the agent having to remember to do it.

cd /path/to/the/worktree/someone/else/created
berth adopt --setup             # register it, apply ports, data and processes
berth status --json             # inspect what it is now running

berth init && berth hook install all   # skill + Cursor worktree adapter

An adopted checkout is never deleted, even with --force. That is the correct default — berth did not create it, so it does not own its removal — but it also means that if your session layer created the worktree, cleaning it up afterwards is still that layer's responsibility.

Choose the layer you are missing

If you already have a session layer you like and your agents keep colliding over ports and databases, the missing piece is the workspace runtime underneath, and berth adopt --setup is the smallest step toward it. If you have berth and no way to see what four parallel sessions are doing, the missing piece is the session layer, and no amount of port allocation will substitute for a review queue. Run both if you need both: they share exactly one contract — a directory with a branch, a port set and a data directory — and berth's side of that contract is a CLI with JSON output, which is the least opinionated thing it could offer a layer above it.