Skip to main content

Coordinator and git-write policy

When two agents share one repository, the most dangerous thing they can do is both reach for git at the same time. ContextRelay prevents that by naming a single coordinator: exactly one role owns every git write - branch, commit, merge, push, and PR. Everyone else uses read-only git and hands the work off.

This page explains the principle (the why) and the exact command and config key that control it (the how).

The single-git-owner principle​

Claude and Codex run as two independent processes against the same working tree (see Why two agents in one session). They cannot see each other's reasoning - they only share what lands in the durable ledger. If both agents could commit and push freely, you would get:

  • Dual-write races - two git commit or git push calls interleaving on the same branch.
  • Ambiguous history - commits whose authorship and intent are unclear because two agents touched the tree between them.
  • Conflicting branches - each agent pushing its own version of the same change.

ContextRelay's answer is governance, not locking: one accountable git owner per repository. That owner is the coordinator. The non-coordinator agent stays useful with read-only git (git status, git diff, git log) and hands any write-shaped work - committing, branching, merging, pushing, opening a PR - back to the coordinator or to the human.

Coordinator is a role, not a person

The coordinator is one of three values: claude, codex, or human. Picking human means no agent performs git writes at all - a person runs every git command. This is the most conservative setting.

How it is configured​

The policy lives in your project's .contextrelay/config.json under the collaboration block:

{
  "collaboration": {
    "coordinator": "claude",
    "gitWrites": "coordinator"
  }
}
  • collaboration.coordinator - which role owns git writes. One of claude | codex | human. The default is claude.
  • collaboration.gitWrites - who may perform git writes. ContextRelay sets this to "coordinator", meaning "only the configured coordinator." It is kept at coordinator whenever you change the coordinator.

You rarely edit this file by hand. The coordinator command sets the config key and rewrites the managed instruction blocks so both agents read the same role.

Changing the coordinator​

Use the coordinator subcommand. The binaries contextrelay, ctxrelay, and context-relay are interchangeable:

# Show the current coordinator and gitWrites policy
ctxrelay coordinator status

# Make Claude the coordinator (this is the default)
ctxrelay coordinator claude

# Hand git ownership to Codex
ctxrelay coordinator codex

# Take all git writes away from both agents
ctxrelay coordinator human

By default the change applies to the current project. Use --scope to control which instruction files are rewritten:

# Update project-level AGENTS.md / CLAUDE.md only (default)
ctxrelay coordinator codex --scope project

# Update the global instruction files (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md)
ctxrelay coordinator codex --scope global

# Update both project and global
ctxrelay coordinator codex --scope both

What this command does in one pass:

  1. Writes collaboration.coordinator (and keeps collaboration.gitWrites at coordinator) in .contextrelay/config.json.
  2. Re-runs the instruction installer for the chosen scope, rewriting the managed ContextRelay block in CLAUDE.md and AGENTS.md so both agents are told the same coordinator and the same git rule.
Restart agents to pick up the new role

Claude Code reads the managed instruction block at startup. After changing the coordinator, restart ctxrelay claude so its startup instructions refresh in the current session. The command prints this reminder for you.

Cycle it from the TUI​

You do not have to leave the dashboard. In the native TUI (run ctxrelay with no subcommand), press c to cycle the coordinator through claude → codex → human. The current coordinator is shown in the dashboard's metrics row alongside autonomy, scanner mode, and finality.

Where the policy is enforced​

The coordinator works on two layers that reinforce each other:

  1. Instruction layer (policy the agents follow). The managed block in CLAUDE.md/AGENTS.md tells each agent who the coordinator is and instructs non-coordinator agents to use read-only git and hand off git-sensitive work. Before attempting git, a non-coordinator agent calls read_context to confirm the current coordinator from the shared ledger.

  2. Permission layer (capability the daemon mediates). Independently of the coordinator role, ContextRelay mediates an explicit set of capabilities - including git - through the daemon. When git is denied (for example in readonly mode), the daemon blocks the operation and returns a reason to the agent. See Read-only by default: safety and containment for how permissions and capability mediation work.

The coordinator decides who commits, not whether it is safe

Naming an agent as coordinator authorizes it to own git writes - it does not, by itself, loosen any other guardrail. Read-only-by-default behavior, autonomy, and autonomous edits (act:write) remain governed by their own gates. The git owner is one decision; safety containment is another.

When to pick each role​

CoordinatorPick it when…Git behavior
claude (default)Claude owns planning and git for the repo; Codex implements and reviews.Claude performs branch/commit/merge/push/PR. Codex uses read-only git and hands off.
codexCodex coordinates planning and implementation, runtime permissions allow git writes, and the human has approved that repo policy.Codex performs git writes. Claude uses read-only git and hands off.
humanYou want no agent touching git - a person runs every git command.Neither agent writes git. Both use read-only git and surface the work for the human.
Codex as coordinator has preconditions

Setting the coordinator to codex is a configuration change. Codex actually performing git writes still depends on its runtime permissions allowing it and the human having approved that policy for the repository. If either is missing, treat git as human-owned and hand the work off.

Handing off git-sensitive work​

When a non-coordinator agent reaches a point that needs a git write, it should not attempt the command - it should delegate. Claude does this with the handoff tool (stating the reason, the concrete ask, and the relevant files); Codex uses handoff_to_claude. The coordinator then performs the write and records the result in the ledger, so the history stays single-owner and auditable. See Handoffs, replies, and deliberation for the mechanics.

Next steps​