Skip to main content

Connect Claude Code

For a machine with no CtrlB account, use Run Recall on your machine.

The ctrlb-agent plugin uploads Claude Code sessions and subagents to CtrlB Recall. It adds the Model Context Protocol (MCP) connection for the five Recall tools and fifteen Relay tools. The hooks use standard-library Python 3.9 or newer.

Get your key​

In the sidebar, under AI operations, choose Connect. Under Your MCP key, choose Generate key, or Rotate key to replace an existing one. The key acts as you, with your roles and dataset grants. The Claude Code tab shows your URL; its copy button fills your key into the copied command.

Set the environment​

Add the three variables to your shell profile, such as ~/.zshrc or ~/.bashrc, and open a new terminal:

export CTRLB_URL="<your CtrlB URL>"
export CTRLB_MCP_URL="<your CtrlB URL>/mcp"
export CTRLB_KEY="<your key>"

The hooks upload to CTRLB_DATASET, which defaults to agent_sessions. If Connect shows another sessions dataset, also set export CTRLB_DATASET="<your sessions dataset>"; the Connect snippet includes this line. CtrlB refuses writes to any dataset other than your workspace's configured sessions dataset.

Environment variables take precedence over the corresponding settings in ~/.ctrlb/config.json. See the Settings reference.

The hooks use CTRLB_URL and CTRLB_KEY for uploads and checks. Claude Code expands CTRLB_MCP_URL and CTRLB_KEY in the plugin's connection configuration. To keep the key value out of your profile, use one of the methods below.

Install the plugin​

claude plugin marketplace add ctrlb-hq/ctrlb-agent
claude plugin install ctrlb-agent@ctrlb-agent

Start Claude Code and run /ctrlb-agent:setup. It checks the hosted connection and offers to upload past sessions.

If you cannot use the marketplace, load the plugin from a clone for each session:

git clone https://github.com/ctrlb-hq/ctrlb-agent.git ~/ctrlb-agent
claude --plugin-dir ~/ctrlb-agent/plugin

Pass --plugin-dir each time you use this route.

Keep the key out of your profile​

Clone the repository and run the configure step yourself, in a terminal, not through an agent:

[ -d ~/ctrlb-agent ] || git clone https://github.com/ctrlb-hq/ctrlb-agent.git ~/ctrlb-agent
python3 -I ~/ctrlb-agent/bin/configure.py

It asks for the URL, the sessions dataset, a run id and the key. The key prompt hides what you type. It writes ~/.ctrlb/config.json with mode 0600, and checks that CtrlB answers. The hooks read that file when CTRLB_URL or CTRLB_KEY is not set. The MCP server still reads CTRLB_MCP_URL and CTRLB_KEY from the environment, because Claude Code expands them in .mcp.json.

The config-reading exports in Run Recall on your machine also read these fields from a hosted config. They keep the key value out of the profile while supplying it to the MCP connection.

Set up with a prompt​

Claude Code can install the plugin and set the environment for you. You do one thing yourself: save the key in a file. Do not give the key to the agent. What the agent reads goes into its transcript, and the transcript goes to the model provider and, with this plugin, to CtrlB Recall.

1. Save the key, in a terminal. The key is not shown when you paste it:

mkdir -p ~/.ctrlb && chmod 700 ~/.ctrlb
( umask 077; printf 'Paste your CtrlB MCP key: '; stty -echo; IFS= read -r k; stty echo; echo; printf '%s' "$k" > ~/.ctrlb/key )

2. Give Claude Code this prompt. Replace <your CtrlB URL> first.

Set up CtrlB for Claude Code on this machine. My CtrlB URL is <your CtrlB URL>.
My MCP key is in ~/.ctrlb/key. Never read, cat, print or copy that file, and never
write the key's value into a command, file or message. Refer to it only as
$(cat ~/.ctrlb/key). To check that the file exists, run: test -s ~/.ctrlb/key && echo present

1. Run: claude plugin marketplace add ctrlb-hq/ctrlb-agent
Then: claude plugin install ctrlb-agent@ctrlb-agent
2. In the profile my $SHELL reads (~/.zshrc or ~/.bashrc), add this block. If a
block marked "# ctrlb" is already there, replace it:
# ctrlb
export CTRLB_URL="<your CtrlB URL>"
export CTRLB_MCP_URL="<your CtrlB URL>/mcp"
export CTRLB_KEY="$(cat ~/.ctrlb/key)"
# end ctrlb
3. Check the key without showing it:
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $(cat ~/.ctrlb/key)" "<your CtrlB URL>/ai/relay/agent_sessions/runs?limit=1"
200 means the request worked. For 401, tell me to check or replace the key.
For 403, tell me to check my role and dataset access with my administrator.
If a later upload or write returns 403 with MCP_WRITES_DISABLED, ask my
administrator to turn on write tools for the CtrlB deployment.
4. Tell me to open a new terminal, start claude, and run /ctrlb-agent:setup.

If Connect shows a sessions dataset other than agent_sessions, change the prompt before you paste it: add export CTRLB_DATASET="<your sessions dataset>" to the profile block and use that dataset name in place of agent_sessions in the check address.

The plugin loads only in a new session, so the restart in step 4 is necessary. /ctrlb-agent:setup then checks the connection and offers to upload your past sessions.

If your organization already installs the plugin through managed settings, remove step 1 from the prompt. To change the key later, save the new key with the terminal command under Save the key, in a terminal and open a new terminal.

Project instructions​

At session start the plugin tells the agent when to search the record: before the first grep, file read or shell command for a question about earlier work, and after a command fails. Every session with the plugin gets this rule.

For earlier work in general, the rule calls search_sessions without session_id to search this user's sessions. The current session id is used only for this session's own turns before compaction; a subagent uses the parent's session id when searching the parent's work.

To keep the rule in the project itself, for example for sessions where the hooks are off, write it into the project's CLAUDE.md from a clone of the repository. The block names the CtrlB tools, so every teammate still needs the plugin connection.

Clone the repository if you have not done so:

[ -d ~/ctrlb-agent ] || git clone https://github.com/ctrlb-hq/ctrlb-agent.git ~/ctrlb-agent

Open a terminal in your project's root directory and run these two commands there. They write to the directory you are in:

python3 -I ~/ctrlb-agent/install.py init --claude --dry-run
python3 -I ~/ctrlb-agent/install.py init --claude

The block sits between <!-- ctrlb:begin --> and <!-- ctrlb:end -->. Text outside the markers is not changed. A file that does not exist is created; a run that would change nothing writes nothing; before a change, the old file is copied to CLAUDE.md.ctrlb-backup-<time>. --dry-run prints the diff and writes nothing, and --remove deletes the block. Add --codex to write AGENTS.md for Codex as well.

Check and remove​

Give Claude Code a task and wait for the turn to end. Open Sessions in the app to find the uploaded transcript. Run /ctrlb-agent:setup to check the connection. Read ~/.ctrlb/hooks.log if records do not appear.

Use CTRLB_OFF=1 claude to turn hooks off for one session. To remove the plugin, run claude plugin uninstall ctrlb-agent@ctrlb-agent, remove the connection exports from your profile, and delete ~/.ctrlb if you no longer need its local config and state. If you used local mode, that folder also holds ctrlb.db with your local records; keep a copy first if you need them. Hosted rows remain. Remove the project block with python3 -I ~/ctrlb-agent/install.py init --claude --remove from your project.

For coordination and edit checks, Start a run. You do not need another install.