Docs

Quickstart

The installer checks Python 3.10+, installs to ~/.codecouncil/app, puts codecouncil on your PATH, wires up pi (the model runtime) if npm is available, and scaffolds the key file. ~80 audited lines; re-run it to update.

That second command installs the Claude Code hooks and runs all three loops. Then type /keys in the running council — guided API-key setup with hidden input (nothing echoed, nothing in shell history), and a model is picked automatically for whichever key you add. Prefer manual? git clone + python3 -m codecouncil /path/to/repo works identically, and scripts can still write ~/.codecouncil/env directly.

Configuring

The running council is interactive — slash commands work in place, Claude Code-style:

/keys              guided API-key setup (hidden input) — then offers that provider's model
/model [p/m]       show (bare) or set + persist the primary model (set restarts just the critic)
/prober <p/m|off>  council mode on/off (restarts just the critic)
/status            daemons, beats, last verdict, heuristics version, keys
/config            resolved configuration and where each value came from
/verbose           toggle idle-beat chatter (default: filtered)

Settings layer the way you'd expect: CLI flag > env var (COUNCIL_MODEL / COUNCIL_PROBER) > ~/.codecouncil/config.json > per-key auto-default. Keys take effect on the next model call — no restarts. Setting a model warns immediately on a missing provider key or malformed id, and a console-set value always beats a stale launch flag or exported env var. Bare /model shows the current model, which layer set it, and examples for the keys you have configured.

Model providers

Any provider pi supports works. The free start: sign in at build.nvidia.com, click Get API Key on any model page, and save it via /keys. With a key present and no model configured, CodeCouncil picks that provider's table entry automatically (first configured key wins, free NVIDIA first, Anthropic last) — /keys alone is a working setup; /model is only needed to switch.

One deliberate caveat: prefer a critic from a different model family than your coding agent — the premise is a second pair of differently-trained eyes.

The two-terminal workflow

codecouncil . in one terminal, Claude Code in the other. The terminal is signal-first: idle-beat chatter is filtered (a dim summary line keeps the pulse; /verbose unmutes), while findings, repro proofs, council votes, grades, heuristics rewrites, and receipts arrive ★ highlighted. The dashboard auto-starts when built and announces its URL:

[ui] dashboard ready → http://localhost:4700/

Rebuttals & receipts

Findings are delivered into your agent's context. If the agent disagrees, it replies with a line the critic records honestly:

COUNCIL-REBUTTAL: <reason>

Rebuttals grade deterministically and distill one repo fact each into a per-repo knowledge file the critic reads on every future judgment — the same disagreement never needs to happen twice. When the agent declares work done, a session receipt (claims made vs. mechanically verified facts) is written to .codecouncil/receipts/.

Security model

Everything is redacted at capture — credentials in diffs, new files, commands, reasoning, or commit messages become «REDACTED» markers before any text is written to disk or built into a prompt. The only thing that leaves your machine is review prompts to the provider you configure; keys live in ~/.codecouncil/env, outside every repo. Repros run in throwaway temp dirs; investigation tools are path-jailed to the repo. Full contract: SECURITY.md.

Running loops individually

python3 -m observer /path/to/repo        # event-driven; 10s fallback floor
python3 -m critic /path/to/repo          # 10s beat; model call only when code changed
python3 -m critic /path/to/repo --prober openrouter/openai/gpt-5-mini   # council mode
python3 -m reflector /path/to/repo       # grade + gated rewrites, every 5 min
python3 -m reflector.report /path/to/repo  # acceptance per heuristics version
python3 -m hooks.install /path/to/repo   # idempotent; peer_hook is fail-open
python3 -m evals.run /path/to/repo       # replay frozen cases against every rules version

Architecture

Four independent daemons — Observer, Critic, Hooks, Reflector — communicating only through append-only NDJSON files in the watched repo's .codecouncil/ directory. Each is independently restartable and crash-safe; byte-offset cursors commit only after judgments durably land. The plain-language tour lives in PROJECT_GUIDE.md; contributor invariants in CONTRIBUTING.md.

Architecture map

Want to understand the codebase fast? A structural knowledge graph is checked into the repo at .ua/knowledge-graph.json, generated by the Understand-Anything plugin:

554 nodes    files, classes, functions, configs, concepts
1,239 edges  imports, calls, contains, tested_by, documents
10 layers    Observation → Critic → Delivery → Reflection → Measurement …
14-step tour observer → critic → hooks → reflector, in data-flow order

With the plugin installed, /understand-dashboard opens it as an interactive graph in seconds — generating it was the expensive part, so the result is committed and reading it is free. Without the plugin the JSON reads plainly: the top-level keys are project, nodes, edges, layers, tour. It's a commit-pinned snapshot, not a live view — .ua/meta.json records exactly which commit it describes.