Cairn

Persistent ground truth for Claude Code. Stop AI agents from drifting.

/plugin marketplace add isaacriehm/cairn
/plugin install cairn@isaacriehm-cairn
/reload-plugins

The Problem · What You Get · Quick Start · Glossary · How It Works · Features · Multi-Dev · Docs

A cairn is a stack of stones marking a trail. This project stacks the decisions, invariants, and canonical references that define your codebase into a single queryable ground state — so every Claude Code session starts with the same map.

The Problem

Monday: you tell Claude Code "auth tokens expire after 24 hours." It ships. Works.

Friday, new session, new prompt. The agent reads auth/tokens.ts, sees no comment about expiry, and "improves" the code to a 7-day refresh. You catch it in review. Or you don't.

The model isn't bad. The model has no memory of what you decided.

A bigger context window doesn't fix this — it just delays it. What fixes it is a structured record on disk that every session reads from and writes to. Cairn is that record, plus the runtime that keeps it load-bearing.

What You Get

Three persistent stores, version-controlled in .cairn/:

🪨 Decisions (DEC-<hash>) — every architectural choice gets a markdown file with rationale, scope, and a supersedes chain. Once accepted, canonical until explicitly replaced. The agent reads the in-scope decisions before touching the affected code.

DEC-a3f7b2c  Auth tokens expire after 24 hours
  Scope:       src/auth/**
  Rationale:   PCI compliance — short-lived bearer tokens
  Supersedes:  DEC-7c2f10a (7-day refresh, deprecated 2026-02-14)

🧭 Invariants (§INV-<hash>) — domain rules whose violation is a bug, not a style preference. "All API responses must include a request-id header." Sensors enforce them on every diff at pre-commit and again at CI.

🗺️ Canonical map — topic → file index. Ask cairn_canonical_for_topic("rate limiting") and get the actual file paths instead of the agent grepping vaguely or fabricating them.

Plus four runtime layers that keep those stores live: an MCP server (29 typed tools), a Claude Code plugin (skills + hooks + reviewer agent), sensors (stub-catalog + decision-assertions), and a CLI for bootstrap and debug.

Quick Start

Inside Claude Code, in any project:

/plugin marketplace add isaacriehm/cairn
/plugin install cairn@isaacriehm-cairn
/reload-plugins

(First registers the GitHub repo as a marketplace; second installs the plugin; third loads it. The plugin ships a self-contained bundle — hooks, MCP server, and CLI all run from dist/cli.mjs inside the plugin cache. No npx, no npm install -g, no PATH dependency.)

Recommended: disable Claude Code's built-in auto-memory before adopting — Cairn is your memory layer and the two conflict:

/memory → Disable Auto-Memory

Open Claude Code in any project. The plugin auto-detects on session start and offers [a] adopt now. Pick [a] once. The pipeline streams inline so you watch what's happening — typically 2-15 minutes depending on repo size.

When it finishes, your next session starts with the full ground state preloaded.

If you want cairn directly on your shell PATH (for cairn doctor, cairn attention, cairn trace, etc.):

npm install -g @isaacriehm/cairn

…but the plugin doesn't require it. Outside Claude Code, you can adopt via CLI instead:

cairn init

Glossary

Read this once and the rest of the doc reads cleanly.

How It Works

Two flows: adoption runs once when you onboard a repo. Daily flow runs on every prompt thereafter.

Adoption (one time)

A single visual pass with 13 phases. The plugin streams output inline so nothing is opaque.

After the pipeline finishes, recorded decisions auto-accept into the ledger (the review checkpoint is the committed diff). The cairn-attention skill drains what's left — baseline sensor findings, drift events, and any dedup-fallback drafts — interactively.

Daily flow

You type a prompt
        │
        ▼
┌────────────────────────────────────────────────┐
│  Plugin auto-invokes the cairn-direction skill │
│   1. Skill loads in-scope DECs, §INVs,         │
│      and canonical-map entries via MCP         │
│   2. Main Claude classifies prompt readiness   │
│   3. If unclear → inline A/B/C questions       │
│   4. If ready → tightens spec inline, writes   │
│      .cairn/tasks/active/<id>/spec.tightened.md│
│   5. Spec dispatched to subagents              │
└────────────────┬───────────────────────────────┘
                 ▼
   Subagents work in your repo with MCP access:
     cairn_decisions_in_scope, cairn_invariant_get,
     cairn_canonical_for_topic, cairn_search, …
                 │
                 ▼
   Reviewer subagent attests the diff,
   extracts non-obvious decisions as DEC drafts
                 │
                 ▼
   Stop hook surfaces inline:
     "Review DEC-b1e9c04 draft? [a] accept [b] reject [c] edit"
                 │
                 ▼
   You commit → pre-commit hook runs sensors
              → CI gate verifies again on PR
              → drift caught before merge

The key bit: the agent never starts cold. Every prompt enters with the relevant decisions, invariants, and canonical references already loaded into the spec.

Features

Memory + ground state

• Persistent decisions / invariants / canonical map in version-controlled .cairn/.
• Component registry — every component file carries a structured @cairn <ExportName> header; the agent loads the full in-scope inventory before any UI work and follows USE > EXTEND > CREATE so it never rebuilds a component that already exists. A check gate blocks missing headers / duplicate names; an advisory audit flags probable inline rebuilds.
• Supersedes chains — old decisions stay readable but flagged superseded; the chain is queryable via cairn_supersedes_chain.
• Scope-aware preload — the SessionStart hook injects only the DECs / §INVs that apply to files you've recently touched, instead of dumping the whole ledger into context.

Adoption

• Single visual pass — operator watches the pipeline stream inline. No opaque background job.
• Haiku-batched classification — docs, source comments, and rules are ingested in parallel for speed.
• Conflict detection — when two sources disagree, surfaces a side-by-side resolution prompt instead of silently picking one.
• Topic-index dedup — content fingerprints prevent the same fact landing as three separate DEC drafts.
• Component-store backfill — projects adopted before the component store shipped add it in one pass: the cairn-adopt-components skill detects the config, dispatches component-annotator subagents to write @cairn headers, and builds the index + singleton §INVs. No manual header-writing — just ask the agent to adopt the component store.

Daily flow

• cairn-direction skill — auto-tightens vague prompts ("fix the bug") into structured specs before dispatch. Loads the in-scope DECs, §INVs, and canonical-map entries automatically.
• cairn-attention skill — drains the queue of dedup-fallback DEC drafts, baseline sensor findings, and drift events interactively (decisions auto-accept; review rides the diff).
• Reviewer subagent — every multi-chunk task ends with the reviewer attesting the diff and extracting non-obvious decisions into DEC drafts.
• Status-line badge — ⬡ cairn in the Claude Code status row shows pending attention count, bypass warnings, GC state, and the active task title. Color-codes by absolute token usage.
• Session trace log — cairn trace pretty-prints unified per-session events. --tail, --errors-only, --session, --json flags supported.

Sensors

The sweep runs as a real gate at pre-commit (cairn sensor-run --staged, blocks on hard findings) and at CI (cairn sensor-run --diff <range> --strict). Live SoT alignment runs separately on every PostToolUse Write/Edit. The Stop hook surfaces task / GC / attention state — it does not run the sensor sweep. Drift events log to .cairn/staleness/log.jsonl and surface on the next GC sweep.

Tooling surfaces

• MCP server — 32 typed tools across read, write, history, attention, init, and search. Used by the plugin and any other MCP client.
• CLI — cairn init / join / mcp / gc / scope / doctor / fix / migrate / attention / align / baseline / hook / sensor-run / tag / trace / status-line.
• Claude Code plugin — manifest + 5 hook events (SessionStart, SessionEnd, Stop, UserPromptSubmit, PostToolUse — matchers Read, Write|Edit, AskUserQuestion) + 3 skills + 1 reviewer agent + 3 commands.
• Cairn Lens — VS Code / Cursor extension. Hover, gutter icons, code lens, optional DEC Explorer sidebar. Resolves §INV-<hash>, §DEC-<hash>, TODO(TSK-…) inline. Read-only — same ground state, no separate index.

Editor Extension — Cairn Lens

Hover, ghost text, gutter icons, code lens — all resolved live from .cairn/ground/ ledgers. Read-only. Hovering a @cairn component header shows its registry entry ([S] singleton; amber drift when the header name ≠ the exported name).

Install the latest .vsix from releases → Cmd/Ctrl+Shift+P → Extensions: Install from VSIX…. Full setup in packages/cairn-lens/README.md. Because the .vsix is not on the Marketplace, Cairn Lens checks npm once a day and notifies you when a newer release is published (disable via cairn.lens.checkForUpdates).

Multi-Developer Enforcement

Once a project is Cairn-adopted, every developer runs Cairn — locally and at PR time. Defense in depth:

Plus Stop-hook bypass detection — flags any HEAD commits not in .cairn/.attested-commits and surfaces [a] backfill / [b] accept (record DEC) / [c] defer.

Disk Layout

After cairn init:

.cairn/
├── config.yaml                  slug, version, off_limits, domain
├── config/                      workflow.md, sensors.yaml, stub-patterns.yaml
├── ground/
│   ├── decisions/               DEC-<hash>.md per choice + _inbox/<id>.draft.md
│   ├── invariants/              INV-<hash>.md per §V rule
│   ├── canonical-map/           topic → file index
│   ├── components/              derived @cairn inventory (gitignored; rebuilt from headers)
│   ├── brand/                   overview.md, voice.md
│   ├── product/                 positioning.md, personas.yaml
│   ├── conflicts/               <a-id>__<b-id>.md (DEC↔INV contradictions)
│   ├── alignment-pending/       ambiguous SoT-align cases queued for review
│   └── scope-index.yaml         file → DEC/§V resolution
├── baseline/                    first-sweep audit YAMLs
├── tasks/active/<id>/           spec.tightened.md, status.yaml, attestation.yaml
├── sessions/<session-id>/       per-session status + events
├── staleness/                   drift event log + deferred Layer-A queues
├── git-hooks/                   pre-commit, post-commit, commit-msg
├── runs/terminal/               one-shot CLI run logs
├── backups/source/              .original snapshots (rules-merge can revert)
├── .attested-commits            commit log used by bypass detection
└── JOIN.md                      new-contributor bootstrap doc

Full contract: docs/FILESYSTEM_LAYOUT.md.

Packages

packages/
├── cairn/                       umbrella + CLI bin (`cairn …`)
├── cairn-core/                  MCP server, sensors, hooks, init pipeline
├── cairn-state/                 ground-state schemas + low-level I/O
├── cairn-frontend-claudecode/   Claude Code plugin (manifest, hooks, skills, agents, commands)
└── cairn-lens/                  VS Code / Cursor extension (.vsix)

Documentation

User guide — read these to use Cairn day to day:

Technical specs — read these when you're modifying Cairn itself:

Development

git clone https://github.com/isaacriehm/cairn
cd cairn
pnpm install
pnpm build
pnpm smokes        # 38-smoke gate. all green on a clean tree.

Other root scripts: pnpm typecheck, pnpm clean, pnpm smokes:all (every declared smoke), pnpm smoke:llm-prompt-eval (opt-in real-Haiku regression — burns quota). See CLAUDE.md for the full table.

Troubleshooting

Skill listing budget on Sonnet (and other lower-context models)

Claude Code reserves 1% of the model's context window for the skill listing by default. On Opus (1M ctx) that's ~10 000 chars — plenty of room. On Sonnet (200k ctx) it's ~2 000 chars, which is tight once you add a few user-level plugins (design skills, image generators, etc.). The cairn family ships ~3 skills + 3 commands; if your listing is over budget, Claude Code drops the lowest-priority descriptions — cairn-direction is a frequent victim, which means the auto-invoke trigger gate never sees the prompt.

Adoption handles this for you. Phase 1 detect raises skillListingBudgetFraction to 0.03 in ~/.claude/settings.json (fits cairn + ~30 user skills on Sonnet). The bump is silent, idempotent, and only fires when the existing value is missing or below the floor — operator overrides at or above 0.03 are preserved. Restart Claude Code after first adoption to pick up the new budget.

If you ever need to verify, run /doctor. It should report 0 dropped. If a value above 0.03 still shows dropped descriptions, disable user-level skills you don't use (the /skills UI toggles each one) or set "user-invocable-only" in skillOverrides (hidden from the auto-invoke listing, still reachable via /<name>).

Status

Pre-1.0. The Claude Code plugin is the daily-driven surface; the CLI is the bootstrap and debug entrypoint. Issues + PRs welcome.

License

MIT © Isaac Riehm