canonkit

A versioned team of AI subagents for Claude Code, Codex and OpenCode. Each agent owns one domain: product, architecture, security, quality, UX, performance, operations or docs. Before it recommends anything, it rates the risk of the change. Small, reversible work stays with your main agent. Changes to auth, secrets, migrations or public contracts go to the agent that owns them. In Claude Code, hooks enforce the rules that matter most, so they hold even when the model forgets them. Codex and OpenCode get the two that matter most of all: no git hook bypass and no secrets written to a file.

Each agent is one Markdown file in agents/, already in the format Claude Code reads. For Claude Code, installing is a plain copy. Codex and OpenCode get a generated copy of the same body. Either way there is one source per agent, and nothing to reconcile by hand.

canonkit 1.x is not canonkit 0.x. Versions up to 0.2.0 were a different tool. It generated Spec-Kit-style governance templates (.specify/, a constitution, scale profiles) through canonkit init. That tool is archived and none of its commands exist here. If you used it, pin [email protected].

Who it's for

• You use Claude Code, Codex or OpenCode with subagents, and you want each one called only when its domain is actually at risk, not on every change.
• You want a few guarantees to hold even when the model forgets them: confirm before git commit and git push, block secrets, and require a review before a HIGH-risk change counts as done.
• You want to see what delegation costs (tokens, time, report size per dispatch) without sending anything off your machine.

It is not a fit if you want one agent per task, or a heavy spec-first process. canonkit can work alongside openspec, but it does not replace it.

Quickstart

Requires Node 18+. On Linux, macOS and Windows:

npx canonkit install --wire-hooks

In a terminal, a menu asks which runtimes to install for. Claude Code and Codex come pre-selected; OpenCode is opt-in. --wire-hooks wires the gate hook of each runtime you chose: ~/.claude/settings.json, $CODEX_HOME/hooks.json (then run /hooks in Codex once to trust it), and the OpenCode 2 plugin. It saves a dated .bak of each config file it changes and changes nothing else. If you leave the flag out, install only prints Claude Code's JSON for you to paste yourself. What each choice writes.

Codex agents default to gpt-6.1-sol. To follow your Codex session's model instead of pinning a version, set CANONKIT_CODEX_MODEL=inherit when installing. See model configuration for PowerShell examples, overrides and updating existing agents.

Check that it worked:

npx canonkit doctor

doctor only reads. It prints one line per check (OK, WARN or FAIL) and exits with 1 if anything failed:

OK   agents: 10 core agents in ~/.claude/agents
OK   reference: managed blocks in ~/AGENTS.md and ~/.claude/CLAUDE.md
OK   hook file: ~/.claude/hooks/canonkit-hook.js, same as this package's
OK   hook syntax: node --check passes
OK   hook wiring: registered with its matcher under PreToolUse, PostToolUse, SubagentStop, UserPromptSubmit, Stop
OK   log: ~/.claude/canonkit-activity is writable
OK   forwarder: no meu-time-hook.js left, and no settings in sight run it
OK   config: file none (defaults), root ~/my-project

No check failed.

Then open a new Claude Code session in any project:

1. /agents should list the ten core agents (scott, archie, bob, ...).
2. Ask it to commit something. You should get a canonkit gate: git commit/push requires explicit user authorization prompt. Decline it; you just saw a gate fire. No prompt? See If no gate ever fires.

Optional: the dashboard. It runs locally and shows dispatches, tokens and gates:

node ~/.claude/canonkit-dashboard/serve.js          # Linux, macOS, Git Bash
node $HOME\.claude\canonkit-dashboard\serve.js      # Windows PowerShell

Then open http://localhost:4317. What it records.

How it decides: LOW vs HIGH

Every agent uses one shared risk scale:

• LOW: local and reversible. No public contract, auth, sensitive data or shared runtime.
• MEDIUM: a new rule, flow, integration, permission or configuration; a shared refactor; a plausible regression.
• HIGH: auth, secrets, migrations, public contracts, new services, payment, a production deploy, or anything that is hard to roll back.

Both examples below come from the routing eval cases:

"Fix the typo recieve in README.md." This is LOW. The main agent fixes it inline and dispatches no one. A dispatch would cost a cold start, plus a report that gets re-read on every later turn, for a one-word fix.

"Add refresh tokens to src/auth/session.js." This is HIGH, because it touches auth. Here is what happens:

1. The main agent plans to bring in Gard (security), the owner of auth.
2. Editing src/auth/session.js fires the HIGH-risk gate, and you confirm the edit.
3. The work is not done on the author's word. When the turn ends, the Stop gate checks whether an independent reviewer (Quinn, Gard, Archie, Perry or a project reviewer) was dispatched, or resumed with a message, after the last gated edit. If none was, it blocks the turn once and asks for one.

There is a case in between: fixing a typo in a comment in src/auth/messages.js. The gate still fires, because the file is in auth/. The risk is still LOW, though, and the expected behavior is to confirm, explain why, and not pull in Gard. A gate tells you to look again at the risk; it does not make the change HIGH.

The team

Core: installed at user level and available in every project.

Specialists: not installed by default. A project gets one only when you add it, so no agent gets called just to round out the list:

cd my-project
npx canonkit add maya nova      # writes Claude Code, Codex and OpenCode copies + the project's AGENTS.md

A veto is narrow. An agent can use its veto only inside its own domain, on a MEDIUM or HIGH change, and only against a risk it can name. You can overrule a veto. When you do, the agent records the open risk and keeps helping. Who owns what at the boundaries, the conventions every agent follows, and the Integration Review are in docs/team.md.

Stack packs, per project

Optional skills add language and framework guidance to the existing team. Choose the packs your project uses; each is installed separately from the core.

Run these commands from your project. You can add several packs at once, inspect what is installed and remove a pack when you stop using it:

cd my-project
npx canonkit add typescript react
npx canonkit list
npx canonkit remove react

React and TypeScript are independent. Adding a pack installs its instructions; it does not install compilers, runtimes or project dependencies.

Copies go to the project's .agents/skills/canonkit-<stack>/ and .claude/skills/canonkit-<stack>/. Local edits and unrelated files are preserved; repeating add updates intact copies. Details, recovery and removal are in docs/install.md.

When a gate fires

This table is Claude Code. Codex and OpenCode, once wired, enforce only the git bypass block and the secret block, with the same reason text (which gate does what where). The git, secret, HIGH-risk and performance prompts start with canonkit gate. The Stop gate starts with Definition-of-done gate. The context-size reminder is plain text.

False alarms. The HIGH-risk gate matches paths, so it will sometimes fire on a folder named sessions/ or contracts/ that has nothing to do with auth. Each project can tune this in .claude/canonkit.json:

{
  "version": 1,
  "highRisk": { "include": ["src/billing/**"], "exclude": ["src/domain/contracts/**"] },
  "perfBudgets": ["perf/thresholds.yml"]
}

exclude can only silence ambiguous words. It never silences the secret check, credential paths (.env, *.pem, ...) or strong terms (auth, jwt, migrations in code). Editing canonkit.json is itself a gate. Don't edit the hook to make a gate stop firing: the next install overwrites it. The full rules are in docs/hooks.md.

If no gate ever fires

Run npx canonkit doctor. The hook fails open on purpose, so a broken or unregistered hook never blocks your session. That also means a broken hook gives no warning of its own.

Runtimes

How each target is generated, and why OpenCode is opt-in: docs/install.md. Which gate does what in each runtime: docs/hooks.md.

Commands

--dry-run works on every command that writes: it reports what would change and writes nothing.

FAQ

What does it cost per turn? Claude Code lists every installed agent's description on every turn. That list plus the two global blocks comes to about 3k tokens. An agent's full body (~1–2k tokens) loads only when the agent is dispatched. Measurements.

Will it dispatch agents on every small change? It shouldn't. LOW work stays inline by rule. Before each release that changes the instructions, the routing eval checks this with cases like the typo fix above. If you see it happen anyway, please open an issue.

Can I edit an installed agent? Not in place: the next install overwrites ~/.claude/agents and the managed blocks. To change one, create a project agent with a different name, or change the source here and reinstall (docs/maintaining.md). Text outside the managed block markers in ~/AGENTS.md and ~/.claude/CLAUDE.md is yours and is preserved.

Does anything leave my machine? The hook keeps telemetry local in ~/.claude/canonkit-activity/; new records omit task descriptions and command fragments, but still include paths and identifiers alongside counts and timing. Older records can retain those texts until rotation. Both incidental project issues and the optional Learning Loop contribution supply sanitized drafts; publication requires your review and explicit authorization. Raw logs and personal memories do not belong in a contribution. Field list.

A gate fired on a change I'm sure is LOW. Confirm it and say why. If the same path keeps triggering the gate for no reason, add it to highRisk.exclude (see When a gate fires).

How do I uninstall? Run npx canonkit uninstall --dry-run to preview, then npx canonkit uninstall (or select harnesses with flags). It uses the install manifest, backs up edited owned artifacts, preserves observed artifacts intact and keeps content outside managed blocks. Pre-manifest installations and ambiguous wiring need manual cleanup; see docs/install.md.

I'm upgrading from meu-time. install migrates the log folder and leaves a forwarder for the old hook name. See docs/install.md.

Documentation

License

MIT