Opt a Repository In
The repository opt-in is shared by Claude Code, Codex, and Pi. Run /ca:init in Claude Code,
$ca-init in Codex, or /ca-init in Pi; all three create or observe the same .codearbiter/
directory. See the Claude Code + Codex evidence for a
worked mixed-host example, and Pi for Pi’s parent-process trust boundary.
The plugin installs once, globally. Enabling enforcement is a per-repo step you run once inside each repository you want covered. Complete the plugin install before starting here.
You will need: Python 3 on your PATH, git config user.email set, and the plugin installed.
/ca:init lane by piece type: commands (gold) and the skills behind them (violet). Init forks to one context-builder path: create-context for existing code, decompose for a new project.1. Scaffold the State Store
Section titled “1. Scaffold the State Store”Open the target repository in one supported host and invoke its native command:
| Host | Command |
|---|---|
| Claude Code | /ca:init |
| Codex | $ca-init |
| Pi | /ca-init |
/ca:init creates .codearbiter/ at the repo root and routes to the right context builder for your situation. If the directory already exists, it will not overwrite what is there.
2. Complete the Context Build
Section titled “2. Complete the Context Build”/ca:init routes based on whether the repository has existing code:
| Your situation | Routed to | What it does |
|---|---|---|
| Existing codebase | /ca:create-context | Scouts the source and back-fills .codearbiter/ |
| New project, no code yet | /ca:decompose | A layered interview that builds .codearbiter/ from scratch |
Let the routed command finish before moving on. It populates the context files the enforcement gates read at commit time.
3. Confirm the Activation Flag
Section titled “3. Confirm the Activation Flag”Open .codearbiter/CONTEXT.md and confirm the leading frontmatter:
---arbiter: enabled---Two things to verify:
- The frontmatter block opens on line 1 and closes with a matching
---. arbiter: enabledappears inside that block.
A file with no frontmatter at all is silently dormant. A frontmatter block that opens but never closes surfaces a malformed-state error rather than treating the repo as disabled.
Once the flag is present and the block is closed, the next supported-host session opens with the orchestrator active and every gate armed.
4. Restart and Prove Enforcement
Section titled “4. Restart and Prove Enforcement”Close the current session and open a fresh one in the same repository. The first response should include the codeArbiter startup briefing: stage, blocking questions, in-flight tasks, and a pointer to the command catalog.
Then run doctor using the same host syntax convention:
| Host | Command |
|---|---|
| Claude Code | /ca:doctor |
| Codex | $ca-doctor |
| Pi | /ca-doctor |
Doctor’s harmless H-03 probe should be blocked. If the briefing is absent or the probe executes, the repository is not proven active. Follow Troubleshooting before starting governed work.
Common Stops
Section titled “Common Stops”| Symptom | Meaning | Recovery |
|---|---|---|
Init reports an existing .codearbiter/ directory | Project state already exists | Inspect it; do not overwrite another session’s context |
| The repo has source but no initialized marker | Brownfield context is incomplete | Complete the routed create-context flow |
| Frontmatter opens but does not close | Activation state is malformed | Repair the frontmatter structure, then restart |
| Fresh session has no briefing | Plugin trust, interpreter, cache, or activation failed | Run doctor and use the symptom table in Troubleshooting |
For the full catalog of what the gates enforce and how they fail, see Enforcement & Security.