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

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

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

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.

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.
• Fast-tier 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) + 5 skills + 5 agents +
  4 commands.
• Cursor plugin — same cairn-plugin package, thin host manifest
  (.cursor-plugin/ + native v1 hooks.cursor.json + mcp.json +
  rules/).
• Codex plugin — .codex-plugin/ manifest + PLUGIN_ROOT hooks +
  bundled MCP config. Works in Codex Desktop and CLI. Codex handles
  multi-file apply_patch calls through the same guardian/alignment
  pipeline.
• One implementation — all three adapters call the same shared skills,
  hook runners, MCP server, agents, and dist/; only the host manifests
  and protocol serializers differ.
• 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-plugin/   Claude Code + Cursor + Codex plugin (thin manifests, one dist/)
└── 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        # default 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-model regression — burns quota). See
AGENTS.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, Cursor, and Codex plugins are the daily-driven
surfaces; the CLI is the bootstrap and debug entrypoint. Issues + PRs
welcome.

License

MIT © Isaac Riehm