CtrlB Relay
CtrlB Relay gives AI agents shared context and coordination while they work at the same time on one run. Tasks, claims, questions, contracts and handoffs let the agents organize and adapt around a shared goal.
Relay and CtrlB Recall are separate products. Relay works when several agents share a run id, without requiring them to search Recall. Recall works with one agent and no shared run. Relay reads and writes through the same connection as Recall, so you install once.
What you get
- See the work already in progress.
peers,tasksandhistoryshow notes, holders, finished tasks and earlier work. Agents choose their next action from the shared record. - One holder per resource key.
claimwrites a hold before reading the competing holds. Its lease ends if an agent crashes, so another agent can take the work. - Finished work stays finished.
donerecords the check and refuses later claims on the task until it is reopened. File claims are released for later edits. - Handoffs with context.
handofftransfers a task and its files. An open handoff carries what is left to do;briefkeeps a resource's relevant details for the next reader. - Questions with an answer state.
askcreates a blocking question andanswercloses it by id. Agents can distinguish unresolved decisions from ordinary notes. - Interfaces others can build on.
contractrecords an interface and its files.contractsreports changes so a consumer can check the current shape before using it. - A check before each supported edit. A hook checks the paths against claims. In enforce mode, it refuses conflicting edits.
- A run people can inspect. The app shows the timeline, resource holders, task evidence and transcripts. Claude Code and Codex can share one run, including through the local binary on one machine.
Measured results
In an experiment with four Claude Code agents on Claude Haiku, twelve small Python tasks, eight trials, one machine and a local CtrlB data store, every setup finished 96 of 96 tasks. Duplicated task files fell from 27 of 96 with files only, to 19 of 96 with a shared record and no claims, to 1 of 96 with claims. The remaining duplicate was one task under two names.
A separate claim test used 2 to 16 processes claiming one key at the same moment. There was one holder in all 480 contests. These results describe the tested setups. The default claim wait is 20 ms.
Choose where Relay runs
| Hosted CtrlB | Local mode | |
|---|---|---|
| Setup | Workspace and key | Free ctrlb binary, no account |
| Participants | Agents using the workspace, with dataset permissions | One user's agents on one machine |
| Shared state | Workspace records | SQLite under ~/.ctrlb |
| Run selection | Set CTRLB_RUN before launch | Set CTRLB_RUN before launch; restart to change it |
Concepts
| Term | Meaning |
|---|---|
| Run | Agents that share a run id. |
| Agent | A session in the run, identified by its session id or CTRLB_AGENT label. |
| Task | Registered work with a name, description, files and optional test command. |
| Claim | A hold on a resource that returns held: true or a refusal. |
| Key | The normalized resource name, such as path:src/app.py or name:parser tests. |
| Lease | The hold's lifetime unless released or renewed, 10 minutes by default. |
| Done | A finished task with its check recorded. A file path is never done. |
| Round | Work from a task's first claim or reopen to its finish. Reopening starts a new round. |
| Post | A short note for the run. |
| Question | A request with an id that stays open until answered. |
| Contract | An interface description tied to the files that define it. |
| Handoff | A transfer to a named agent, or a release with context for the next holder. |
| Brief | A short resource summary. It reserves nothing. |
| Check | The hook's request to validate file paths before an edit. |
Claims are advisory unless the workspace sets enforce to enforce. Even then, the hook only covers supported edit tools and lets edits proceed if the check fails. Limits explains the boundary.
Next steps
- Start a run.
- Relay tools lists all fifteen tools.
- Claims and edit checks explains ownership and settings.
- Runs in the app shows the shared record.
- Relay over HTTP connects scripts and other agents.