What SuperBench is
SuperBench gives each task its own git worktree on a host, called a bench, and keeps it warm between the agents or people who take turns on it. One holder works in a bench at a time. Before the bench can pass to the next holder, the work has to be committed, pushed to the task branch and confirmed on the remote.
It is a Go command-line tool, bench, and an optional local daemon, benchd, that serves the same
operations over a Unix socket. It has no TCP listener (read from the source; no test asserts it, see
the Security model) and depends on no other suite product. Output is JSON.
Why a bench
Section titled “Why a bench”A coding task usually needs a checkout, installed dependencies and a build cache before any useful work starts. When several agents take turns on one task, each starting from a fresh clone is slow, and sharing one checkout without rules loses work. A bench is the middle ground:
- One task, one checkout.
bench createmakes a worktree for the task from a shared git mirror, on its own task branch (bench/<key>by default), and runs the repository’s setup. - Kept warm. The checkout, its ignored build output and its caches stay on the host between holders, so the next holder starts where the last one stopped.
- One holder at a time.
bench leasegrants the bench to one holder and refuses otherbenchacquisitions until the holder releases it. See Leases for what that does and does not stop. - Checkpoints the remote confirms.
bench checkpointpushes the existing HEAD without force and fails unless the remote branch is exactly that commit.bench releaserefuses until that is true. See Checkpoints. - Recoverable, in part. Because the committed work is on the remote,
bench recovercan rebuild a bench from its remote-confirmed task branch into a separate, empty state and data pair. Recovery into existing state is not supported, and no second-host recovery drill exists yet; see Status.
The basic loop, from the repository README (flags precede the task key):
bench create --repo /absolute/path/to/remote.git fix-loginbench lease --holder first-agent fix-login# Save Lease.Token from the response in BENCH_LEASE_TOKEN and cd to Path.# Edit files, git add, and git commit as usual. Then:bench checkpoint fix-loginbench release fix-loginbench lease --holder second-agent fix-loginbench status fix-loginThere is no supported installation yet: the loop above shows what the commands do, not a way to start using SuperBench.
The loop as written needs Linux. Whenever the repository has setup hooks or a supported lockfile,
warm create, recover, lease and setup prepare the checkout in a fenced execution, which
needs Linux cgroup delegation. On a laptop the cooperative sequence is create-cold, then
lease-repair, then prepare-local, then acknowledge-local-preparation; see
Supervised runs and setup.
What it is not
Section titled “What it is not”- Not released. There are no tags, no published binaries and no supported installation. Nothing here is in production use.
- Not a sandbox. Leases are cooperative, and supervised runs on Linux are fenced in a cgroup, which is process-tree fencing; there is no user or mount isolation. SuperBench is for trusted repositories. See the Security model.
- Not multi-host. It runs on one host. Moving a bench to another host is a reviewed administrative procedure, not network coordination.
- Not integrated with the rest of the suite. Suite adapters, remote authentication and a web interface are not built.
Where to go next
Section titled “Where to go next”- Status: what works on
main, what is partial, what is not built. - Benches and workspaces: the two shapes a bench takes.
- bench CLI: every command and flag as the source defines them.