cairn

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

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.

No more re-explaining the architecture. No more the agent picking the opposite of what you decided last week. No more "wait, where does X live?"

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.)

Open Claude Code in any project. The plugin auto-detects on session start and offers [a] adopt now. Pick [a] once. Done.

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

npm install -g @isaacriehm/cairn

…but the plugin doesn't require it.

Adoption is a single visual pass — submodule init, repo walk, mapper, brand setup, doc ingestion, source-comment ingestion, rules merge, sensor sweep, multi-dev install. The plugin streams the output inline so you see what's happening. After it finishes, agents in your next session start with full ground state.

Outside Claude Code? Same thing via CLI:

npm install -g @isaacriehm/cairn
cairn init

Why

I'm a solo developer. I let Claude Code drive most of my coding. The problem isn't that the model is bad — the problem is that every new session starts with no memory of what I decided yesterday. The agent picks an interpretation. Sometimes it's the one I wanted. Sometimes it re-debates a decision I already made and silently goes the wrong way.

The fix isn't a bigger context window. It's a structured, queryable ground state on disk that every session reads from + writes to. Cairn is that.

Three pillars:

• 🪨 Decisions stack up over time, each with a rationale, scope, and supersedes chain. Once accepted, they're canonical until explicitly superseded — never silently re-litigated.
• 🧭 Invariants are domain rules whose violation is a bug, not a style preference. Sensors enforce them on every diff.
• 🗺️ Canonical map answers "where does X live?" in one MCP call — no fuzzy grep, no fabricated paths.

How It Works

You type a prompt
        │
        ▼
┌───────────────────────────────────────────────┐
│  Plugin auto-invokes cairn-direction skill    │
│   1. Tier-0 classifier (Haiku) → ready?       │
│   2. If not ready → inline A/B/C questions    │
│   3. If ready → tightener (Sonnet) drafts spec│
│   4. 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 drafts
                 │
                 ▼
   Stop hook surfaces inline:
     "Review DEC-0099 draft? [a] accept [b] reject [c] edit"
                 │
                 ▼
   You commit → pre-commit hook runs sensors
              → CI gate verifies on PR
              → drift caught before merge

Features