Skip to main content

CtrlB Recall

CtrlB Recall keeps the full record of your coding agents' work and gives agents tools to search it. You can recover an earlier decision after compaction, reuse a fix from another session, or search a teammate's work when your hosted permissions allow it.

Recall and CtrlB Relay are separate products. Recall works with one agent and no shared run. Relay coordinates several agents that share a run id, without requiring them to use Recall. Relay reads and writes through the same connection as Recall, so you install once.

What you get​

  • A record beyond the summary. Recall stores each message, thinking block, tool call and tool result that the harness exposes, including subagents. You can read the original steps behind a decision.
  • Search the agent can call itself. Five Model Context Protocol (MCP) tools read stored records without a model call. search_sessions finds earlier turns, including this session's turns before compaction. session_index lists recent sessions before you choose one to read.
  • A path from failure to the next action. find_command finds an earlier command. next_actions shows its result and what the agent tried next. fetch_records supplies the surrounding text.
  • Search across work. Omit the session id to search your other sessions. Hosted access can include teammates' sessions through the relay.read_all permission.
  • Secret replacement before upload. The plugin replaces text matching common credential patterns before it sends rows. What is uploaded and limits explains the coverage.
  • Records your workspace can query. Hosted records are ordinary dataset rows. Read them in the Log Explorer, query them with the SQL query guide, or use them in alert rules.
  • Records on your machine. Local mode keeps records in one SQLite database. ctrlb push copies session records to hosted CtrlB when you want to move.

Choose where Recall runs​

Hosted CtrlBLocal mode
SetupA workspace and a keyFree ctrlb binary, no account
StorageYour workspace's sessions datasetSQLite under ~/.ctrlb
ScopeYour sessions and permitted team recordsOne user on one machine
ConnectionYour CtrlB URLWorks without a network connection after installation

Concepts​

TermMeaning
SessionOne conversation in Claude Code or Codex. Subagent records link to their parent session.
RecordA stored row for a message, thinking block, tool call, tool result or session result.
DatasetThe collection of records, named agent_sessions by default.
HarnessThe application that runs the coding agent, such as Claude Code or Codex.
CompactionThe harness replaces earlier context with a shorter summary. Uploaded records remain searchable.

How records arrive​

The Claude Code plugin and Codex hooks read the local transcript. They upload new lines at the end of each turn, before compaction, when subagents start or stop, and at session end. The hosted connection sends them to your workspace; local mode sends them to SQLite. A script can also upload records over HTTP.

The record is limited by what the harness exposes and by text size limits. For example, Codex supplies reasoning summaries, but no encrypted reasoning or developer messages. The search rule asks the agent to use Recall; it cannot force a search.

Next steps​