Getting Started

Requirements

• Python 3.12+
• git, on PATH
• An agent CLI such as claude, installed and authenticated
• A target repository that is a git work tree with a clean working tree

Install

python3 -m venv .venv && source .venv/bin/activate
pip install -e .
cco --version

Scaffold a project home

Convention: one orchestration home per project. A home holds config.yaml and a runs/ directory, so each project has its own routing ladder, budgets and run history. --home creates both. It refuses to overwrite an existing config.yaml unless you pass --force.

Profile routed

Two tiers, claude:sonnet then claude:opus, with one escalation. The classes simple, docs and standard all start at claude:sonnet.

cco config init --profile routed --home ~/my-project-home

Profile routed-minimax

Puts a MiniMax tier first: minimax:MiniMax-M3, then claude:sonnet, then claude:opus. simple and docs start on MiniMax; standard starts on claude:sonnet.

cco config init --profile routed-minimax --home ~/my-project-home
export MINIMAX_API_KEY='<your-key>'
export CODIFIED_ORCHESTRATOR_HOME=~/my-project-home

Generated config.yaml shape

For routed-minimax the runner section looks like this. The <python> placeholder is the interpreter that ran config init.

runner:
  env_passthrough: [MINIMAX_API_KEY]
  routing:
    tiers:
      - {executor: command, name: minimax, model: MiniMax-M3,
         executor_cmd: "<python> -m codified_orchestrator.command_adapters.minimax_exec"}
      - {executor: claude, model: sonnet}
      - {executor: claude, model: opus}
    classes: {simple: 0, docs: 0, standard: 1}
    max_escalations: 1

The profile writes no API key. It only lists MINIMAX_API_KEY in env_passthrough. The routed profile has the same shape without the MiniMax tier and without env_passthrough.

Check readiness

cco doctor

Write a first contract

A contract is a JSON document (schema 1.0). Required fields: schema_version, contract_id, task, allowed_files and verify_commands. Save this as contract.json:

{
  "schema_version": "1.0",
  "contract_id": "demo-001",
  "task": "Make greeting() strip whitespace and fall back to 'world'",
  "allowed_files": ["app/greeting.py", "tests/test_greeting.py"],
  "verify_commands": ["python3 -m pytest -q"]
}

• allowed_files is the write scope: an exact path, a directory prefix ending in /, or a glob. A change outside it is an unexpected_mutation and is rolled back.
• verify_commands run without a shell. Shell syntax (|, &&, ;, >) is rejected. All must exit 0.

Contracts created by cci-contract start have the same shape.

Run it guarded

cd /path/to/repo
cco run --task-class standard --executor-sandbox \
  --contract-file contract.json 'see contract'

--task-class picks the start tier from the routing ladder. To bypass routing and use one executor, pass --executor claude instead. --executor-sandbox turns on the agent CLI's own sandbox; without it a kept run is reported degraded.

Read the outcome

Exit code 0 means the change was kept, 1 means it was rolled back or failed, and 2 means the run was blocked before execution (bad contract, dirty working tree, missing executor). Details are in <home>/runs/<run_id>/task_outcome.json.

Useful fields: state, diagnostic_code, next_command, verify_ok, mutated_files, unexpected_mutations, rollback_performed. When a run is rolled back, the rejected diff is saved as rejected.patch in the run directory. cco trace <run_id> replays the phase events.

Close the contract

A ready outcome alone is not acceptance. Acceptance happens in codified-context-infra: cci-contract close validates task_outcome.json against the outcome schema and accepts or rejects the contract. The contract is accepted only when close does not return invalid or verified_memory_pending.

cci-contract close --help

Use the help output for the options your installed cci-contract version expects.

Watch runs

cco observatory

Opens a read-only dashboard at http://127.0.0.1:4173.