Skip to main content

Install and first run

ContextRelay connects Claude Code (Anthropic) and Codex (OpenAI) into one auditable coding session on your own machine. This page gets you from nothing to a verified, ready-to-pair setup. If you want the bigger picture first, read What is ContextRelay.

The flow is four short steps: install prerequisites, install the package, run ctxrelay init, and verify.

Prerequisites​

ContextRelay coordinates two CLIs and runs its daemon on Bun. Install and authenticate all three before you continue - ctxrelay init checks for each binary and stops if one is missing.

# Bun - the daemon and the Claude plugin server run on Bun
curl -fsSL https://bun.sh/install | bash

# Claude Code (v2.1.80 or newer - older versions can't use plugin channels)
npm install -g @anthropic-ai/claude-code

# Codex CLI
npm install -g @openai/codex

After installing, make sure both agents are signed in (run claude and codex once and complete their auth flows). ContextRelay drives your existing Claude and Codex installs - it does not provide its own model credentials.

Why Bun?

The ContextRelay daemon and the Claude Code plugin server both run on the Bun runtime. Node alone is not enough; ctxrelay init will fail its dependency check if bun is not on your PATH.

Install ContextRelay​

npm install -g @proofofwork-agency/contextrelay

This installs three interchangeable binaries - contextrelay, ctxrelay, and context-relay. They are the same CLI; this guide uses ctxrelay.

First-time setup: ctxrelay init​

Run init from the root of the repository you want the agents to work in:

ctxrelay init --instructions project

init performs five steps and is safe to re-run (it skips work that is already done):

  1. Checks dependencies - verifies bun, claude (>= 2.1.80), and codex are installed. It exits with guidance if any is missing.
  2. Generates project config - creates .contextrelay/config.json with conservative defaults and assigns this project a unique instance ID and a loopback port group.
  3. Installs collaboration instructions - writes a managed ContextRelay block into the repo's CLAUDE.md and AGENTS.md so both agents know how to collaborate (see --instructions scope below).
  4. Registers the Claude Code plugin - registers the ContextRelay plugin marketplace and installs the plugin (best-effort; it prints a fallback if this step can't run).
  5. Prints next steps - including a reminder to run /reload-plugins and the commands to start each agent.
Safe-by-default config

The config init writes is read-only by default. Backup-agent autonomy is off (autonomy.enabled: false), autonomous edits (act:write) are off (autonomy.writableAction.mode: "off"), the idle scanner is off (autonomy.idleScanner.mode: "off"), and finality requires human acceptance (autonomy.autoFinalize: false). Nothing edits files or spawns extra agents until you explicitly opt in. See Read-only by default.

Register the ContextRelay MCP tools for Codex​

init wires up the Claude plugin. To give Codex its ContextRelay tools (so it can message Claude, hand off, and read the shared ledger), run:

ctxrelay codex-mcp install

This registers the ContextRelay MCP server with Codex globally, so any Codex session in the project can use the tools. See the MCP tools reference for what each agent gets.

Choosing the instruction scope​

The --instructions flag controls where the managed collaboration block is written. The block is delimited by <!-- contextrelay:start --> and <!-- contextrelay:end --> markers, so ContextRelay can update it later without touching your own content.

ValueWhere the block is written
projectThe repo's CLAUDE.md and AGENTS.md (recommended)
globalYour home CLAUDE.md / AGENTS.md and ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md
bothProject and global
skipDon't write any instruction files
ctxrelay init --instructions both   # teach this repo and all your sessions
ctxrelay init --instructions skip   # config + plugin only, no doc edits

If you omit --instructions in an interactive terminal, init prompts you (defaulting to project). You can change scope later at any time with ctxrelay instructions install --scope <scope>. To learn how to tune coordinator and policy from here, see Configure collaboration policy.

Verify the setup​

Two commands confirm everything is wired correctly.

doctor runs a full diagnostic - binaries, provider auth, project config, daemon health, plugin registration, and stale state:

ctxrelay doctor

Each line reports OK or a specific problem with a fix. To skip the (slower) live Claude/Codex auth probes, use ctxrelay doctor --no-auth.

status prints the live daemon, session, ledger, and policy state. Add --json for machine-readable output:

ctxrelay status
ctxrelay status --json

You can also list every ContextRelay project on this machine and the ports each one uses:

ctxrelay instances

If doctor reports a problem, Troubleshooting and recovery walks through the common cases.

You're ready to pair​

Setup is done. From here, the fastest path is the first paired session tutorial, or read Daily operation for the launch / inspect / stop loop. In short, you start each agent with:

ctxrelay claude   # start Claude Code with the ContextRelay channel enabled
ctxrelay codex    # start Codex connected to the same daemon
ctxrelay pair     # or start both terminals plus the dashboard at once

Keeping ContextRelay current: ctxrelay upgrade​

When a new version ships, update the package and then reconcile your already-installed setup:

npm install -g @proofofwork-agency/contextrelay@latest
ctxrelay upgrade

upgrade brings your existing project into line with the new package - safely and idempotently. It:

  • migrate-merges .contextrelay/config.json - it adds any new default keys while preserving your existing values (coordinator, activation state, permissions, write-mode settings, and so on are left untouched);
  • refreshes the managed instruction blocks in CLAUDE.md / AGENTS.md, preserving each file's slim/dormant or full state;
  • refreshes the bare /contextrelay command only if you already have one installed;
  • re-registers and reinstalls the Claude Code plugin so it picks up the new bundles;
  • prints the from → to version and reminds you to run /reload-plugins in any running Claude Code session.

Useful flags:

FlagEffect
--dry-runCompute and print the full plan, but write nothing and run no plugin install
--no-pluginSkip the Claude plugin re-register/reinstall step
--instructions <refresh|project|global|both|skip>Control instruction-file handling (refresh only touches files that already have a managed block; project/global/both also install where missing; skip touches none)
What upgrade does not do

upgrade never changes your coordinator or your activation (auto-connect vs dormant) state, never runs git or npm operations, and never restarts the daemon for you. It will not un-slim a dormant file or add managed blocks to files that don't already have one (that is what init is for).

On an older release without upgrade?

If your installed version predates the upgrade command, use the manual fallback: re-register the plugin and refresh instructions yourself, then verify.

ctxrelay dev                                  # re-register marketplace + reinstall plugin (rebuilds from source)
ctxrelay instructions install --scope project # refresh the managed instruction block
ctxrelay doctor                               # confirm the result

Contributors: developing ContextRelay from source​

If you cloned the repo to work on ContextRelay itself, use dev instead of the shipped plugin registration. It builds the CLI and plugin bundles from source and registers a local marketplace:

ctxrelay dev

End users installing from npm do not need this - ctxrelay init handles plugin registration for them.

Next steps​