Skip to main content

Frequently asked questions

Short answers to the questions that come up once you understand the basics. Each answer links to the page that explains it in full, so use this as a map rather than a substitute for the concept pages.

The two agents​

Do Claude and Codex see each other's chat or hidden reasoning?​

No. The two agents run as separate processes and share only what is written into bridge messages and the shared ledger - never each other's private chain-of-thought. If a fact matters to the other agent, it has to be stated explicitly in a message, a handoff, or an append_note entry.

tip

Treat the ledger as the team's working memory. When you delegate, write the goal, the files touched, the blockers, and the next step into the message - the peer cannot infer any of it. See Handoffs, replies, and deliberation.

Why run two agents at all instead of one?​

So one agent can implement while the other reviews, and so risky calls get a real second opinion before they ship. The pairing also leaves a durable, auditable record of who did what. The reasoning is laid out in Why two agents in one session.

Can a plain codex window join, or only ctxrelay codex?​

Either, depending on how you set it up. After you run ctxrelay codex-mcp install once, the ContextRelay MCP tools are registered globally, so a normal codex window opened in the project can load them and participate. Running ctxrelay codex-mcp remove unregisters them, which restricts participation to sessions launched with ctxrelay codex.

ctxrelay codex-mcp install   # let any codex window in this project join
ctxrelay codex-mcp status    # show current registration
ctxrelay codex-mcp remove    # restrict to `ctxrelay codex` only

See Configure collaboration policy and the MCP tools reference.

Git and the coordinator​

Which agent is allowed to commit, push, or open a PR?​

Only the coordinator (or you). The coordinator is a single configured role that owns all git writes - branch, commit, merge, push, PR - so there is never a dual-write race. In a fresh project the configured default coordinator is claude; non-coordinator agents are expected to use read-only git and hand off git-sensitive work.

ctxrelay coordinator status     # show the current coordinator
ctxrelay coordinator codex      # make Codex the coordinator

Full details (including the human option and how the role is mirrored into the agent instruction blocks) are in Coordinator and git-write policy.

Safety and cost​

Will the agents edit my files or spend money on their own?​

No - not by default. ContextRelay is read-only by default: backup-agent autonomy is off, and autonomous edits (act:write) are off.

Turning on autonomous edits is deliberate, not accidental

Even after you opt in with config, act:write will not write a single file unless every gate passes at once: a hard environment flag (CONTEXTRELAY_WRITE_MODE_ENABLED), a positive daily USD cap (CONTEXTRELAY_WRITE_DAILY_CAP_USD), per-task budgets and allowlists, and an ephemeral git worktree for containment. Even then it never commits, merges, or pushes - the daemon captures the diff and tears the worktree down. Config alone can never enable writes.

If you do want to enable it, follow Enabling act:write (autonomous edits) safely and Autonomy, idle scanner, and safe automation.

How do I know when work is actually "done"?​

Finality is human-gated by default. Agents can signal completion with the propose_final tool (or /contextrelay:finalize), but the proposal waits in a queue until a human accepts it - typically from the browser viewer. You can opt into automatic finalization with ctxrelay finalize auto, and switch back with ctxrelay finalize manual. See Finality and human sign-off.

Where it runs and where data lives​

Does this run in the cloud or need a server?​

No. ContextRelay is entirely local. A loopback-only daemon coordinates the agents over localhost and is token-authenticated; all durable state lives under .contextrelay/ in your project (the JSONL ledger, session registry, and activation markers), plus a small per-user instance registry. Nothing is sent to a ContextRelay backend - there isn't one. The Architecture overview and Trust boundaries and threat model cover the boundaries.

Do I need a single-vendor account for both agents?​

No. ContextRelay is provider-neutral - it coordinates two separate products rather than reselling either. You just need working, authenticated Claude Code and Codex CLIs already installed on your machine. ctxrelay doctor will tell you if either binary or its auth is missing. See Install and first run.

Which command name should I use - ctxrelay or contextrelay?​

Whichever you like. contextrelay, ctxrelay, and context-relay are three names for the exact same CLI (the package is @proofofwork-agency/contextrelay). This FAQ uses ctxrelay for brevity. The full surface is in the CLI command reference.

Turning it on and off​

Can I keep ContextRelay off until I want it?​

Yes. Make it dormant-by-default for your user with ctxrelay standalone on - that flips the global activation flag and slims the always-on instruction blocks so idle sessions stay quiet. When you want a specific session to participate, opt it in with ctxrelay attach (or the /contextrelay slash command); turn it back off with ctxrelay detach (or /contextrelay:off). To check what the gate currently resolves to and why, run:

ctxrelay gate-check --why

Activation resolves through a fixed precedence - the CONTEXTRELAY_AUTO_CONNECT env var wins, then a per-session attach marker, then project config, then the global flag, then the shipped default (on). The whole model is explained in Activation: auto-connect vs dormant-by-default.

Upgrading​

How do I upgrade after updating the npm package?​

Run ctxrelay upgrade. After you update the package (npm i -g @proofofwork-agency/contextrelay@latest), this command reconciles the rest of your setup to the new version. It is idempotent and safe to run repeatedly.

ctxrelay upgrade --dry-run   # preview every change first, write nothing
ctxrelay upgrade             # apply it

upgrade migrate-merges .contextrelay/config.json so new default keys are added while your existing values (coordinator, permissions, write-mode, and the rest) are preserved; refreshes the managed CLAUDE.md/AGENTS.md blocks in place, keeping each file's slim-or-full (dormant) state; refreshes the bare /contextrelay command only if you already have one; re-registers and reinstalls the Claude plugin; and prints the from → to version with a reminder to run /reload-plugins. Useful flags: --dry-run, --no-plugin (skip the plugin step), and --instructions refresh|project|global|both|skip.

On an older release without ctxrelay upgrade?

You can reconcile the same surface manually: ctxrelay dev (re-register the plugin), ctxrelay instructions install (refresh the managed blocks), and ctxrelay doctor (verify the result). Full guidance is in Upgrading ContextRelay.

Next steps​