codekeel

Drift governance for agentic coding. codekeel keeps a decision ledger for your project (architectural choices, conventions, and constraints) and enforces it live during Claude Code sessions, so every new session inherits, respects, and extends what was already decided instead of silently re-inferring (and contradicting) it from code alone.

Free and open source (AGPL-3.0). Runs entirely on your machine (no account, no server, no telemetry).

npx codekeel install

Sets up the Claude Code integration (hooks + slash commands) in your current project. From inside a session, use /decision to record an architectural decision (it's added to the ledger and injected into every future session automatically). Set ANTHROPIC_API_KEY (see below) to additionally have every edit under that decision's scope semantically verified against it before it lands.

The ledger lives in ledger/DECISIONS.yaml in your project (or ~/.codekeel/GLOBAL_DECISIONS.yaml for conventions that apply across every project you work in), plain YAML, readable and editable by hand.

The four stages

1. Capture, record a decision via /decision, or accept one codekeel noticed on its own.
2. Inject, every active decision loads into context automatically at the start of each session.
3. Enforce, pattern-checkable decisions are checked locally, for free, on every edit; with ANTHROPIC_API_KEY set, judgment-dependent ones are checked live against a model too.
4. Review, contradictions and stale entries surface for a quick human call, never a silent guess.

Installation

Running bare npx codekeel (no subcommand) triggers install automatically the very first time you run it. install does four things, each independently idempotent, safe to re-run any time:

1. Registers five Claude Code hooks in ~/.claude/settings.json: Stop, UserPromptSubmit, PreToolUse (matching Edit|Write|MultiEdit), SessionStart, and PostToolUse (matching AskUserQuestion). Any hooks you already have for other tools are preserved untouched.
2. Adds a rule block to ~/.claude/CLAUDE.md explaining the scope-confirmation gate (only its own marked section is touched, never the rest of the file).
3. Installs a slash command into ~/.claude/commands/: /decision.
4. Seeds this project's ledger (ledger/DECISIONS.yaml) with six curated starter rules, only if the project doesn't already have one.

No account and no network call at any step, everything above is written to your own machine.

Hooks and slash commands are global, set up once per machine, shared by every project you open in Claude Code afterward. The ledger is not: it lives inside each repo, so a brand-new project needs its own npx codekeel install (or just npx codekeel ledger init if the hooks are already set up).

Optional: bring your own Anthropic key

Everything above works with zero setup. Setting ANTHROPIC_API_KEY in your environment additionally unlocks:

• Live semantic enforcement, a diff is checked against a judgment-dependent decision by calling Anthropic directly, in addition to the free local pattern checks.
• Admissibility and contradiction checks, when you record a decision, whether its invariant is concrete enough to enforce, and whether it conflicts with an existing one.
• Conversation mining (opt-in, off by default, see npx codekeel settings), scans recent conversation turns for decision-shaped moments you never wrote down.
• FEATURES.md derivation, a one-time grouping of your codebase's exports into cross-cutting features.

codekeel calls Anthropic's API directly from your machine using this key (there is no codekeel-hosted relay, and codekeel never sees this traffic or bills you for it). Every one of these checks fails open (never blocks an edit) when no key is configured.

Exceptions to enforcement

Sometimes a decision is right in general but wrong for one specific edit (e.g. a "no auth bypass" rule that shouldn't block a quick localhost-only test). When a check denies an edit, the reason it gives may suggest confirming a scoped exception: Claude asks you a real question via AskUserQuestion, and a "Yes" answer is captured automatically as a temporary authorization for the rest of the session. Nothing about the underlying decision changes (no ledger entry is edited or superseded), and the exception applies to both live model checks and the free local pattern checks.

An authorization is genuinely temporary: it expires on its own after 2 hours of no further use (renewed each time it's actually relied on), never lives longer than 8 hours total regardless of use, and only 5 can be active at once (oldest evicted first). To see or end one manually before that:

npx codekeel ledger exceptions              # list what's currently active
npx codekeel ledger revoke-exception <id>   # end one early

Every exception that actually changed a real decision's outcome (not just any confirmed question, only ones that turned a would-be violation into an allow) is permanently logged to ledger/EXCEPTIONS.yaml for audit: which decision, which file, why, and when. That file is git-tracked and never pruned, so it stays a durable record even after the authorization itself has expired, been evicted, or been revoked.

Cross-branch decision conflicts

The contradiction check that runs when you add a decision only sees what's active on your own branch at that moment, it has no visibility into a decision someone else independently added on a different branch. A plain git merge just interleaves the ledger's YAML; nothing flags two branches that each recorded a contradictory decision.

npx codekeel ledger check-merge main feature-branch

Compares the two branches' ledgers against their common ancestor and reports two things: any decision whose active/superseded status disagrees between the branches (free, no key needed), and, with ANTHROPIC_API_KEY set, any newly-added decision that semantically contradicts something already active on the other side. Nothing is auto-resolved, this is a report for a human call, the same posture as every other contradiction check in codekeel. Exits non-zero when it finds a real conflict, so it's usable as a merge gate.

Subagents

The live scope-confirmation gate tracks which files a session has already touched this turn. Claude Code subagents (spawned via the Task tool) share their parent session's own session_id, so tracking keyed on that alone would let a subagent's edits bleed into the parent's (or a sibling subagent's) own file-touch history, producing false-positive denials for edits the current agent never made.

codekeel additionally keys this tracking on Claude Code's own agent_id field, present on every subagent-originated tool call and absent on the parent's. A foreground session and any subagents it spawns, even running concurrently, each get independent scope-gate tracking as a result. No configuration needed.

Commands

Command	Description
codekeel (no subcommand)	First run: same as codekeel install. Every run after that: scans your local session logs for governance signals (discussion loops, a bloated CLAUDE.md, scope creep, code churn) and offers a tip for whichever it finds
codekeel install	Set up hooks, slash commands, and an optional seeded ledger
codekeel settings	Enable or disable individual tools (all on by default except conversation mining)
codekeel trim	Review MD-file trim suggestions (stale references, redundant lines in CLAUDE.md and other root-level docs) and optionally apply them, the only way this ever runs, nothing generates trim suggestions in the background
codekeel ledger add	Add a new decision to the ledger
codekeel ledger init	Seed an empty ledger with universal best-practice rules
codekeel ledger promote <id>	Move a project decision to the global ledger
codekeel ledger demote <id>	Move a global decision into this project's ledger
codekeel ledger review-candidates	Review decisions mined from code patterns and conversation, not yet recorded
codekeel ledger dismiss-candidate <id>	Drop a pending candidate without recording it
codekeel ledger candidate-context <id>	Show more context behind a candidate before deciding
codekeel ledger review-stale	Review active decisions flagged for staleness (dead scope, or never exercised)
codekeel ledger retire <id>	Mark a decision superseded with no replacement, kept as audit trail, no longer enforced
codekeel ledger confirm-active <id>	Confirm a decision is still valid, resets its staleness clock
codekeel ledger exceptions	List currently active session exceptions (temporary decision overrides)
codekeel ledger revoke-exception <id>	Manually end an active exception before it expires
codekeel ledger check-merge <base> [head]	Check whether decisions added independently on two branches (head defaults to the current branch) conflict with each other before you merge, both a free status-divergence check and, with ANTHROPIC_API_KEY set, a semantic contradiction check on each new decision

Most also accept --json, that's how /decision drives them non-interactively from inside a session.

Files on your machine

Every file codekeel reads or writes, and why. All plain text, all inspectable, nothing hidden.

In your project:

Path	Written by	Description
ledger/DECISIONS.yaml	install / ledger init / /decision	Your project's decision ledger. Meant to be git-committed and reviewed like any other source file.
ledger/EXCEPTIONS.yaml	internal, on a real override	Permanent, append-only audit trail of confirmed exceptions that actually overrode a decision, never pruned, independent of the underlying (temporary) authorization's own expiry.
FUNCTIONS.md	a background hook, after a real session	Auto-maintained inventory of every function/class/export, so an agent can check before writing something that already exists.
PROJECT_STATE.md	a background hook, after a real session	A running log of what happened in each session, fed back into every new session's context automatically.

On your machine, shared across every project:

Path	Written by	Description
~/.claude/settings.json	install	The five hook command registrations. Merged in, any hooks you already had for other tools stay as they were.
~/.claude/CLAUDE.md	install	One marked section explaining the scope-confirmation gate.
~/.claude/commands/decision.md	install	The /decision slash command's instructions.
~/.codekeel/GLOBAL_DECISIONS.yaml	ledger add --global / ledger init --global	Your personal, cross-project ledger.
~/.codekeel/settings.json	codekeel settings	Which tools are enabled.
~/.codekeel/state.json	internal, every run	Local behavioral memory: pending review queues, cached verdicts, recent scope confirmations. Nothing in this file is ever sent anywhere.

Privacy

• Local and free, no network call ever: recording a decision, loading your ledger into a session, and pattern-based enforcement.
• BYOK checks (see above): only run when ANTHROPIC_API_KEY is set, and go straight from your machine to Anthropic under your own key (codekeel is never in that path).

License

AGPL-3.0. See LICENSE and CONTRIBUTING.md.