Skip to main content

Connect Codex

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

The installer adds CtrlB's Model Context Protocol (MCP) server and hooks to Codex. The hooks upload sessions and subagent threads from ~/.codex/sessions to Recall. They replace text that matches secret patterns before upload. The connection supplies five Recall tools and fifteen Relay tools.

You need Codex CLI version 0.166 or newer and Python 3.9 or newer.

Set the connection​

In the sidebar, under AI operations, choose Connect. Generate your key and choose the Codex tab. Add these variables to your shell profile 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.

Codex reads the key from CTRLB_KEY when it starts. The installer never writes its value to config.toml. You can use the config-reading exports after saving a hosted config with the configure step.

Run the installer​

git clone https://github.com/ctrlb-hq/ctrlb-agent.git ~/ctrlb-agent
cd ~/ctrlb-agent
python3 -I install.py --codex --dry-run
python3 -I install.py --codex

The dry run prints the diff and writes nothing. Keep the clone where it is; installed hooks call codex/hook.py in it.

Start Codex and run /hooks once to trust the hooks. Codex skips new or changed hooks until you do this. Before approval, hooks do not upload sessions, check edits or inject the session-start rule.

Add project instructions​

Codex reads AGENTS.md in your project at the start of every session, with no approval step. The project block gives Codex the search rule even before you trust the hooks. It 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.

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.

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 --codex --dry-run
python3 -I ~/ctrlb-agent/install.py init --codex

--dry-run prints the change as a diff and writes nothing. The block sits between <!-- ctrlb:begin --> and <!-- ctrlb:end -->:

  • If AGENTS.md does not exist, it is created.
  • If it exists, the block is added at the end. Your text is not changed.
  • If the block is already there, only the text between the markers is replaced. A run that would change nothing writes nothing.
  • Before a change, the old file is copied to AGENTS.md.ctrlb-backup-<time> beside it.
  • --remove deletes the block and nothing else. --dir names another project directory.

Commit AGENTS.md so everyone who opens the project in Codex gets the block. The block names the CtrlB tools, which come from the MCP server that install.py --codex adds, so every teammate still runs install.py --codex once.

What the installer writes​

The installer writes one block in ~/.codex/config.toml, between a line that starts with # >>> ctrlb-agent and # <<< ctrlb-agent. It preserves text outside the block.

[mcp_servers.ctrlb]
url = "<your CtrlB URL>/mcp"
bearer_token_env_var = "CTRLB_KEY"
env_http_headers = { "X-CtrlB-Run" = "CTRLB_RUN", "X-CtrlB-Agent" = "CTRLB_AGENT" }

The URL comes from --mcp-url, then CTRLB_MCP_URL, then the saved mcp_url in the config file, then the CtrlB URL with /mcp. That last URL comes from CTRLB_URL or the saved url. The headers carry the shared run id and your agent label when set.

Hook eventAction
SessionStartStarts a local server when needed; injects the Recall rule and, for Relay, the run and agent context.
SubagentStartUploads the parent's new lines and tells the subagent its parent and ids.
PreCompactUploads new transcript lines.
SessionEndHands off remaining holds in a Relay run, then uploads new lines.
Stop, SubagentStopUploads in the background.
PreToolUse, matching apply_patchChecks the patch's update, add, delete and move paths.

Codex has no hook after a tool call. Its handoff cannot list observed edits or tests, and its done evidence has no hook witness. Claims and edit checks explains the checks and their limits.

Backups and options​

Before a change, the installer copies the old config to config.toml.ctrlb-backup-<time>. Running it again with the same settings writes nothing. New settings replace the marked block. An existing MCP server named ctrlb outside the block causes a refusal; remove that entry with codex mcp remove ctrlb before retrying.

Option after --codexEffect
--dry-runPrint the diff without writing.
--mcp-url URLSet the server URL explicitly.
--codex-home DIRUse a different home; otherwise use CODEX_HOME, then ~/.codex.
--config FILEEdit this config file.
--otelAlso configure OpenTelemetry (OTEL) export; see Connect over HTTP or OpenTelemetry.
--uninstallRemove the marked block, with a backup.

Check, past sessions and removal​

After trusting the hooks, give Codex a task and wait for its turn to end. Open Sessions in the app to read the transcript. Hook errors go to ~/.ctrlb/hooks.log.

  • Upload past sessions with python3 -I ~/ctrlb-agent/bin/backfill.py --codex. It lists what it would send and asks first; --count only lists.
  • Turn hooks off for one session with CTRLB_OFF=1 codex.
  • Remove the config block with python3 -I ~/ctrlb-agent/install.py --codex --uninstall.
  • Remove the project block with python3 -I ~/ctrlb-agent/install.py init --codex --remove from your project. Remove the connection exports from your profile. Hosted records remain.

Start a run when you want agents to coordinate through this connection.