Configure collaboration policy

ctxrelay init gives you working defaults, but before you put two agents to work in a repository there are three policy questions worth answering deliberately:

1. Who owns git? One agent - the coordinator - is allowed to branch, commit, merge, push, and open PRs. The other hands git work to it.
2. What are the agents allowed to do? ContextRelay mediates a set of capabilities (read, write, shell, network, git, …) and can flip the whole pair to read-only.
3. Do the agents actually know the rules? Both Claude and Codex learn the policy from instruction blocks installed into CLAUDE.md / AGENTS.md. No blocks, no shared rules.

Every choice on this page is persisted in .contextrelay/config.json and mirrored into the instruction blocks, so it survives restarts and is visible to both agents. You can re-run any command at any time to change it.

Binaries are interchangeable

contextrelay, ctxrelay, and context-relay are the same CLI. This page uses ctxrelay. The package is @proofofwork-agency/contextrelay.

1. Set the git owner (coordinator)

The coordinator is the single agent allowed to perform git writes. Picking one owner avoids two agents racing on the same branch and keeps your history clean. The default coordinator is claude.

Check the current setting:

ctxrelay coordinator status

Set it to whoever will own git for this repo:

# Claude owns git (default)
ctxrelay coordinator claude

# Codex owns git
ctxrelay coordinator codex

# A human owns git; both agents stay read-only on git
ctxrelay coordinator human

Setting the coordinator does two things in one step:

• Writes collaboration.coordinator into .contextrelay/config.json (and pins collaboration.gitWrites to coordinator).
• Rewrites the managed instruction blocks so both agents read the same role. The git-write policy text inside CLAUDE.md / AGENTS.md changes to name the new owner and tell the non-coordinator to use read-only git and hand off git-sensitive work.

By default the rewrite targets the project scope. Use --scope to also update your global home-directory blocks:

ctxrelay coordinator codex --scope both   # project + global (~/.claude, ~/.codex)

Restart to refresh a live session

The command prints a reminder for a reason: Claude Code reads its startup instructions when it launches. After changing the coordinator, restart ctxrelay claude so the running session picks up the new role.

For the full reasoning behind the coordinator model - why a single git owner, and how non-coordinator agents verify the role before touching git - see Coordinator and git-write policy.

2. Set what the agents are allowed to do (permissions)

ContextRelay mediates eight capabilities and a global read-only switch. When a capability is denied (or read-only is on), the daemon blocks the operation and tells the agent why.

The eight capabilities are:

read   write   shell   network   git   secrets   browser   external_api

Inspect the current policy (it prints the raw permissions block from config):

ctxrelay permissions status

Read-only review sessions

Flip the whole pair to strictly read-only - useful when you want the agents to review, reason, and propose, but never modify files, run shells, or touch git:

ctxrelay permissions readonly on
ctxrelay permissions readonly off   # back to normal development

Allow or deny a single capability

ctxrelay permissions deny network        # block outbound network for the pair
ctxrelay permissions allow network       # re-enable it

Per-agent overrides

Scope a change to one agent with --agent <agentId> (for example, claude or codex). This writes a per-agent override and leaves the other agent on the global policy:

ctxrelay permissions readonly on --agent codex   # Codex read-only, Claude unchanged
ctxrelay permissions deny shell --agent claude   # Claude cannot run shells

Reset

ctxrelay permissions reset                 # restore default global policy (all allowed, readonly off)
ctxrelay permissions reset --agent codex   # drop just Codex's overrides

Permissions live in .contextrelay/config.json under permissions (readonly, allowed, agentOverrides).

These permissions are the pair's policy, not full autonomy or write-mode

This page configures what the two agents may do during normal collaboration. The riskier, unattended capabilities are separate and off by default: read-only backup agents (ctxrelay autonomy) and autonomous edits (ctxrelay write-mode, "act:write") sit behind their own explicit, layered gates. Leave them off until you have read Read-only by default.

3. Manage the instruction blocks

The instruction blocks are how the agents learn the policy. ContextRelay installs a managed ## ContextRelay Collaboration section - delimited by HTML comment markers - into CLAUDE.md, AGENTS.md, ~/.claude/CLAUDE.md, and ~/.codex/AGENTS.md. Everything between the markers is owned by ContextRelay; your own content outside the markers is never touched.

Check which targets have the block installed:

ctxrelay instructions status

Install or remove the blocks for a scope:

ctxrelay instructions install --scope project   # CLAUDE.md + AGENTS.md in this repo
ctxrelay instructions install --scope global    # ~/.claude/CLAUDE.md + ~/.codex/AGENTS.md
ctxrelay instructions install --scope both
ctxrelay instructions remove  --scope project

status defaults to both; install and remove take an explicit --scope. The installed block always reflects the current coordinator, so installing after a ctxrelay coordinator change keeps the two in sync.

Keep the blocks installed

For any project where you want the pair to follow policy, keep the blocks installed. Without them the agents have no shared rules to read, and handoffs, the coordinator role, and the git policy won't be honored.

4. Register ContextRelay's tools for Codex

So far the policy lives in config and instructions. For Codex to participate - send messages, hand off, deliberate, read the shared ledger - it needs ContextRelay's MCP tools registered. (Claude Code gets these from the bundled plugin installed during ctxrelay init.)

ctxrelay codex-mcp status     # show whether the server is registered
ctxrelay codex-mcp install    # register the ContextRelay MCP server for Codex (global)
ctxrelay codex-mcp remove     # unregister it

install runs codex mcp add under the hood, registering the server globally for Codex. Once registered, even a plain codex window opened inside the project can load the tools and attach to the session - you are not limited to launching with ctxrelay codex. Use remove if you want to restrict participation to ctxrelay codex only.

For the list of tools each agent gets, see the MCP tools reference.

Where it all lives

Choice	Command	Persisted in
Git owner	ctxrelay coordinator …	collaboration.coordinator + instruction blocks
Capabilities / read-only	ctxrelay permissions …	permissions
Rules the agents read	ctxrelay instructions …	CLAUDE.md / AGENTS.md managed block
Codex tool registration	ctxrelay codex-mcp …	Codex global MCP registration

The full schema is documented in the config.json reference, and every command above is in the CLI command reference.

A recommended starting posture

For a new project, a sensible default is:

• Coordinator = whoever will own git for this repo. If you are not sure, leave it at the default (claude), or set human if you want to drive all git yourself.
• Permissions = read-only off for normal development; turn it on only for a deliberately read-only review session.
• Autonomy and write-mode = leave off (the defaults). Don't enable unattended backup agents or autonomous edits until you have read the safety concepts.
• Instruction blocks = installed for the project; add global if you pair across many repos.

These are all reversible. Re-run the commands any time your workflow changes.

Next steps

• Coordinator and git-write policy - why a single git owner, and how the non-coordinator hands off.
• Read-only by default - the safety model behind permissions, autonomy, and act:write.
• Daily operation: launch, inspect, stop - run the pair once the policy is set.
• Upgrading ContextRelay - keep config and instruction blocks in sync after an update.