cairn

Cairn

Persistent ground truth for AI coding agents. First-class support for Claude Code, Cursor, and Codex. Stop agents from drifting.

Claude Code

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

Cursor

Settings → Cursor → Plugins → Add from GitHub → isaacriehm/cairn

Codex CLI

codex plugin marketplace add isaacriehm/cairn
codex plugin add cairn@cairn

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, Cursor, or Codex session starts with the same map.

The Problem

Monday: you tell your coding agent "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 (typed tools), a shared agent plugin (skills + hooks + reviewer briefs), sensors (stub-catalog + decision-assertions), and a CLI for bootstrap and debug.

Quick Start

Claude Code

/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

Cursor

Settings → Cursor → Plugins → Add from GitHub → isaacriehm/cairn

Or via the command palette: search "Add Plugin from GitHub", enter isaacriehm/cairn. Cursor reads .cursor-plugin/marketplace.json from the repo root and installs packages/cairn-plugin/ directly — same self-contained bundle as Claude Code, no npm install required.

Codex Desktop and CLI

codex plugin marketplace add isaacriehm/cairn
codex plugin add cairn@cairn

The repo marketplace lives at .agents/plugins/marketplace.json. Codex Desktop and the CLI load the same .codex-plugin/plugin.json, shared skills, MCP server, hook runtime, and committed bundle. In Codex Desktop, restart after adding the repo source, open Plugins, select Cairn, and install it. Review and trust the bundled hooks when Codex prompts; plugin hooks do not run before that explicit trust step.

Native model backend

Cairn's bounded classification and mapping calls use the CLI of the host that loaded the plugin—claude, cursor-agent, or codex—through one shared runner. The host manifests pass their provider explicitly, while a standalone CLI invocation auto-detects an authenticated supported CLI. Use --model-provider auto|claude|cursor|codex to override that selection.

The runner exposes semantic fast and capable tiers instead of leaking provider model names through the codebase. Claude maps those tiers to Haiku/Sonnet, Codex uses gpt-5.3-codex-spark for Cairn's bounded tasks, and Cursor uses its auto routing. Calls are non-interactive, ambient-context isolated, schema-validated, cached per provider, and require no separate SDK or API key. Codex runs in its read-only sandbox; Cursor runs without --force from a temporary workspace with project-level shell/read/ write denies.

---

Open Claude Code, Cursor, or Codex in any project. The plugin auto-detects on session start and offers [a] adopt now. Pick [a] once. The pipeline streams inline — 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 the plugin, you can adopt via CLI instead:

cairn init

Glossary

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

Term	Means
DEC	Decision record — one architectural choice with rationale + scope + supersedes chain.
§INV	Invariant — a domain rule the codebase must obey. Violations are bugs.
Scope	The file glob a DEC or §INV applies to (src/auth/**, packages/billing/**).
Canonical map	topic → file index. The single source of truth for "where does X live?"
Sensor	A mechanical check on a diff: stub patterns, decision violations.
Attestation	A subagent's signed-off summary of what changed and why; drives task auto-graduation.
Drift	When code or docs disagree with the ground state in .cairn/.
Bypass	A commit that skipped Cairn's hooks (--no-verify, broken hook path). Detected and surfaced.
Attention queue	The pile of DEC drafts, baseline findings, drift events, and conflicts waiting for operator review.
Tightener	The host agent step that turns a vague prompt into a structured spec before dispatching subagents.

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.

Phase	What happens
1. Detect	Probe environment + framework signals.
2. Walk	File manifest, extension stats, language detection.
3. Map	Capable-tier domain mapper proposes module boundaries + scope-index.yaml globs.
4. Seed	Write .cairn/ skeleton, config.yaml, grandfather pre-adoption commits into .attested-commits.
5. Pilot	Operator picks a seed module from the mapper's top-3 candidates (one A/B/C question).
6. Brand	Auto-fill brand / voice / product DEC drafts from the mapper's domain summary (one A/B/C).
7. Topic index	Content-fingerprint pre-pass — dedupes facts that appear across docs, source, and rules before drafting DECs.
8, 9, 10 (parallel)	Docs ingest + Source comments ingest + Rules merge (CLAUDE.md / AGENTS.md) — all fast-tier batched.
11. Baseline	First sensor sweep against a synthetic full-tree diff. Findings written to .cairn/baseline/.
12. Strip	Per-module strip-replace consent — operator chooses keep / strip / skip for each flagged module.
13. Multi-dev	Detects package manager, installs git hooks, emits JOIN.md for new contributors.

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