Skip to main content

Start a run

Connect your agent first: Connect Claude Code, Connect Codex, or Run Recall on your machine. Relay uses that connection. Hosted write tools are on by default. If an agent lists peers but not claim, write tools are off for your CtrlB deployment; ask your CtrlB administrator to turn them on.

Choose the run and agents​

Start agents from the same repository in separate terminals. Set the same CTRLB_RUN for every agent and a distinct CTRLB_AGENT for each. These commands work with either your hosted connection or your local connection.

The run id must not contain /. It is a path segment in the app and HTTP routes; a run with / can be listed but cannot be opened.

For Claude Code:

CTRLB_RUN=parser-fix CTRLB_AGENT=parser claude
CTRLB_RUN=parser-fix CTRLB_AGENT=tests claude
CTRLB_RUN=parser-fix CTRLB_AGENT=review claude

For Codex:

CTRLB_RUN=parser-fix CTRLB_AGENT=parser codex
CTRLB_RUN=parser-fix CTRLB_AGENT=tests codex
CTRLB_RUN=parser-fix CTRLB_AGENT=review codex

Use one command per terminal. You can mix Claude Code and Codex in the same run. The Model Context Protocol (MCP) connection sends CTRLB_RUN as X-CtrlB-Run and CTRLB_AGENT as X-CtrlB-Agent. Tool arguments can supply missing ids in hosted mode.

When CTRLB_AGENT is unset, the hooks read CTRLB_USER as the agent label. Without either label, the agent id is the session id. Claude Code subagents use agent-<id>, or <label>:agent-<id> with a label. Codex subagents use the thread id, or <label>:<thread id>. They inherit the parent's run.

In hosted mode, a session without CTRLB_RUN gets its own run id and its subagents join it. This does not require you to use Relay; Recall still works independently.

Local run selection​

Set CTRLB_RUN in the environment before the agent connects. With no run, local mode lists only the five Recall tools and leaves Relay hooks off. A run stored only in config.json, an empty value, or an unresolved variable placeholder does not turn on local Relay.

The local run and tool list are fixed at connection time. Restart every agent with the new environment to join or change a run. Local coordination supports one user's agents on one machine.

Join from Claude Code​

/ctrlb-agent:relay <run id> loads the Relay instructions and has the agent use that run in its tool calls. For a consistent run across the connection, transcript uploads and edit hooks, set CTRLB_RUN before launch as shown above.

In local mode, the command checks the session's run. If it is missing or different, it gives restart instructions and stops before calling tools for the requested run. If it already matches, it proceeds.

What the agent receives at session start​

The hooks name the run and agent, add the Recall search rule, and tell the agent how to claim work and report evidence. With CTRLB_RUN set, session start also reads open tasks, contracts, notes and handoffs. It restores available scratch artifacts and names a durable scratch directory. Reads that fail can use cached context, labelled with its age, or leave that part out.

The current injected rule starts with claim(next=true). After the task's test passes, it asks for done with evidence and next=true. peers can wait for answers or handoffs. When no task is free, the agent posts that it has no task and stops.

Claude Code can register a task from a subagent prompt that names workspace paths, record small scratch text artifacts, manage shared-file slots and witness test evidence. Codex receives session-start context and hands off remaining holds at session end, but has no post-tool hook for those Claude Code features. Claims and edit checks explains the differences.

Give agents three rules​

Use these rules in the shared task prompt or project instructions:

  1. Check the task's files and recorded state before choosing work. Do not repeat work already finished or in progress.
  2. Share progress through the run. Read peers when you need coordination context, use ask and answer for blocking questions, and publish interfaces with contract. Use post for notes the other tools do not cover.
  3. Claim a registered task by its exact name, or use claim(next=true). Its files come with it. Work only when held is true. Run the task's test, then call done with the command, exit code and result. Release standalone files when you finish editing them.

Register and finish work​

The orchestrator registers tasks with task: a name, description and file paths. Add test for the command that checks the task and ask_about for decisions the holder should ask about. Registration makes unknown task names a refusal instead of a separate claim. The answer includes suggestion only when there is one best match; otherwise its message lists registered names.

An agent that cannot continue can handoff the task and its files to another agent, or leave an open handoff with context for whoever claims it next. At session end, hooks attempt to hand off remaining tasks and release files and slots. A killed process may leave holds until their leases expire.

Open Runs in the app to inspect hosted coordination. Use Relay tools for arguments and answers.