Skip to main content

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, tasks and history show notes, holders, finished tasks and earlier work. Agents choose their next action from the shared record.
  • One holder per resource key. claim writes 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. done records the check and refuses later claims on the task until it is reopened. File claims are released for later edits.
  • Handoffs with context. handoff transfers a task and its files. An open handoff carries what is left to do; brief keeps a resource's relevant details for the next reader.
  • Questions with an answer state. ask creates a blocking question and answer closes it by id. Agents can distinguish unresolved decisions from ordinary notes.
  • Interfaces others can build on. contract records an interface and its files. contracts reports 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 CtrlBLocal mode
SetupWorkspace and keyFree ctrlb binary, no account
ParticipantsAgents using the workspace, with dataset permissionsOne user's agents on one machine
Shared stateWorkspace recordsSQLite under ~/.ctrlb
Run selectionSet CTRLB_RUN before launchSet CTRLB_RUN before launch; restart to change it

Concepts​

TermMeaning
RunAgents that share a run id.
AgentA session in the run, identified by its session id or CTRLB_AGENT label.
TaskRegistered work with a name, description, files and optional test command.
ClaimA hold on a resource that returns held: true or a refusal.
KeyThe normalized resource name, such as path:src/app.py or name:parser tests.
LeaseThe hold's lifetime unless released or renewed, 10 minutes by default.
DoneA finished task with its check recorded. A file path is never done.
RoundWork from a task's first claim or reopen to its finish. Reopening starts a new round.
PostA short note for the run.
QuestionA request with an id that stays open until answered.
ContractAn interface description tied to the files that define it.
HandoffA transfer to a named agent, or a release with context for the next holder.
BriefA short resource summary. It reserves nothing.
CheckThe 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​