Codified Orchestrator (CCO) Documentation
A guarded runner for third-party coding agents. CCO runs the agent, checks the result against a contract, and keeps or rolls back the change.
What is CCO?
CCO (cco) is a guarded runner for third-party coding agent CLIs. It does not write code itself. It launches an agent against a git repository, then enforces a contract on whatever the agent did: which files may change, and which commands must pass. If the result is clean and verified, the change is kept. Otherwise the working tree is restored.
Supported executors: claude is supported; codex and opencode are beta; a generic command adapter runs any program and has been proven with MiniMax-M3.
What is a guarded run?
Every cco run follows the same pipeline:
- Baseline - the runner records HEAD, branch, the ignored-file set and
.gitmetadata hashes. - Sandboxed executor - the agent CLI runs with its own sandbox enabled (
--executor-sandbox) and writes directly to the repository. - Post-hoc scope check - after the agent stops, the runner diffs against the baseline and rejects anything outside the contract's
allowed_files. - Shell-free verify - the contract's
verify_commandsare run by the runner, without a shell, stopping at the first failure. - Keep or roll back - a clean, verified run is kept. Anything else is rolled back, with the rejected diff saved as
rejected.patch.
Every run leaves execution_envelope.json (how it was executed) and task_outcome.json (what happened) in its run directory.
Enforcement is post hoc: the agent writes directly and CCO detects and reverses violations inside the repository. The agent's own report of success is informational only.
Key Capabilities
Guarded runs
Baseline, sandboxed executor, scope check, shell-free verify, then keep or roll back.
Contract governance
Contracts are opened and closed by cci-contract from codified-context-infra. CCO makes them enforceable.
Model routing ladder
Start on a cheap tier and escalate on failure, for example minimax:MiniMax-M3 → claude:sonnet → claude:opus.
Observatory dashboard
A read-only local dashboard over run artifacts: outcomes, cost, routing ladders and phase timelines.
Project Status
Quick Start
Requires Python 3.12+, git, and an agent CLI such as claude. The target repository must be a git work tree with a clean working tree.
1. Install CCO
pip install -e . cco --version
2. Scaffold a project home
cco config init --profile routed-minimax --home ~/my-project-home export CODIFIED_ORCHESTRATOR_HOME=~/my-project-home
3. Run Doctor
cco doctor
4. Run a task against a contract
cco run --task-class standard --executor-sandbox --contract-file contract.json 'see contract'
The next page, Getting Started, walks through writing the contract and reading the outcome.
Where to go next
| Page | Covers |
|---|---|
| Getting Started | Install, scaffold a home, write a contract, run it guarded, close it |
| Architecture | CCI governance vs CCO execution, the run pipeline, routing, records |
Background: Codified Context: Infrastructure for AI Agents in a Complex Codebase (arXiv:2602.20478).