Skip to content
Not released yet. SuperBench is an experimental single-host prototype under active development. Nothing is released or supported for use yet. These docs describe themain branch and will be refreshed at the first release.

What SuperBench is

wet paint: New or experimental.Open as Markdown

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.

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 create makes 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 lease grants the bench to one holder and refuses other bench acquisitions until the holder releases it. See Leases for what that does and does not stop.
  • Checkpoints the remote confirms. bench checkpoint pushes the existing HEAD without force and fails unless the remote branch is exactly that commit. bench release refuses until that is true. See Checkpoints.
  • Recoverable, in part. Because the committed work is on the remote, bench recover can 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):

Terminal window
bench create --repo /absolute/path/to/remote.git fix-login
bench 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-login
bench release fix-login
bench lease --holder second-agent fix-login
bench status fix-login

There 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.

  • 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.