cairn

Local codebase intelligence system: structural graph + compass + wiki + agent memory.

cairn builds a precise, language-aware structural graph of your codebase and exposes it to both humans (the cairn CLI) and AI agents (a stdio MCP server with 27 tools). Symbols, call edges, definitions, blast radius, and tribal memory all live in a local SQLite store — no network call, no torch in the default install.

What is cairn?

cairn is a local codebase intelligence system. It parses your repos with tree-sitter into a structural graph (definitions, call edges, cross-repo dependencies) stored in SQLite, then layers a compass (per-module navigation guides), a wiki (architecture docs), memory (decisions / patterns / mistakes / workarounds), and a knowledge store on top. It is MCP-native: the same store backs the cairn CLI and a 27-tool MCP server, making it agent-first — your coding agents query one local source of truth instead of re-reading the whole repo every turn.

Why cairn? Resolution-labeled edges

Every code graph can tell you "who calls this." cairn is the one that tells you whether to trust the answer. The resolver labels each call edge:

• exact — pinned to one definition. Trusted.
• ambiguous — multiple candidates; the resolver declined to guess.
• unresolved — external or stdlib.

Graph tools default to precise mode — they follow only exact edges. So blast radius is never inflated by name collisions. A common name like invoke can have hundreds of call sites across a polyglot repo that merely share the name; precise mode returns only the real callers, while fuzzy mode (--fuzzy / fuzzy=True) adds the name-only matches as an explicitly-labelled candidate list to verify.

cairn impact invoke              # precise (default): real callers only — ground truth
cairn impact invoke --fuzzy      # candidate list (name matches), each labelled unverified

An empty precise result means "no resolvable callers," not "unused" — retry with --fuzzy before concluding a symbol is dead. And explore surfaces ambiguous dispatch hops — polymorphism that grep fundamentally cannot see.

This is measurable: see docs/benchmarks.md for the precise-vs-fuzzy false-positive methodology, and docs/examples/resolution-walkthrough.md for a worked example. Full design at docs/architecture.md § Resolution model.

Quick start

pip install cairn-intel              # install from PyPI (the recommended path)
cairn build                         # parse the workspace and build the graph (first run)
cairn update                        # incremental reindex after the first build
cairn def SomeSymbol                # find where a symbol is defined
cairn ask "how does auth work"      # natural-language query across all layers

The graph lives under ~/.cairn by default (override with CAIRN_HOME).

First run vs later runs. cairn build parses every file from scratch. cairn update reindexes only what changed since the last build (via git diff HEAD plus the existing graph) — so on a fresh clone with a clean working tree, use cairn build first, since cairn update would see no changes.

Upgrading

cairn can update itself in place — it detects how it was installed (uv tool, pipx, or pip) and re-installs the latest version from PyPI:

cairn upgrade          # update to the latest published version
cairn upgrade --check  # only check what's latest, don't change anything
cairn version          # print the installed version

If PyPI is unreachable, cairn upgrade prints the manual command instead.

Install for AI agents

cairn ships a stdio MCP server (cairn serve). To wire it into your AI coding clients (Claude Code, Cursor, Droid, ZCode, Claude Desktop, agy, opencode):

cairn install-agents

This detects which clients are installed, shows whether cairn is already wired in, and interactively prompts you to choose:

Client detection:
  [✓] claude           claude CLI on PATH              cairn: [ ] not installed
  [✓] cursor           Cursor.app in /Applications     cairn: [ ] not installed
  [✓] zcode            ~/.zcode exists                 cairn: [✓] installed

Install cairn for which clients?
Clients [claude,cursor]:

Config scope:
  workspace  — write to ./.claude/, ./.cursor/ etc. (per-project)
  global     — write to ~/.claude/, ~/.cursor/ etc. (all projects inherit)
Scope [workspace]:

Scope: workspace (default) writes configs to the current project dir (./.claude/, ./.cursor/); global writes to your home dir (~/.claude/, ~/.cursor/) so all projects inherit cairn without per-project setup.

Non-interactive flags for scripts/CI:

cairn install-agents --yes                          # auto-install detected-not-installed
cairn install-agents --client claude --client cursor  # force specific clients
cairn install-agents --scope global                 # write to ~/.claude/ etc.
cairn install-agents --force                        # overwrite existing files
cairn install-agents --dry-run                      # preview without writing

Or wire manually — the MCP config is:

{
  "mcpServers": {
    "cairn": {
      "command": "cairn",
      "args": ["serve"]
    }
  }
}

The recommended first call from an agent is explore(query), which returns matching symbols' verbatim source, the call paths between them, and a blast-radius summary in a single round trip.

Supported languages

Kotlin, Java, Python, Swift, TypeScript, JavaScript, Dart, Objective-C, Go

Optional features

The default install is dependency-light and network-free. Opt in with extras:

Architecture (5 layers)

The MCP server exposes 27 tools across five layers:

CLI

The cairn command groups the main functionality. Run cairn --help (or cairn <group> --help) for the authoritative, full list.

Development

pip install -e ".[dev]"   # pytest + watchdog + build
pytest -m core            # fast <3s smoke subset (one test per core function)

Semantic search

The default install is network- and torch-free. Semantic search deps (torch + sentence-transformers) are a one-time separate download that persists in ~/.cairn/lib/ (survives reinstalls):

cairn embed --install-deps    # one-time: downloads bge-m3 (~836 MB)
cairn embed                   # builds the embedding index

Development

cairn is developed on GitHub and released to PyPI. The recommended install for end users is pip install cairn-intel (see Quick start above). The following is for contributors only:

pip install -e ".[dev]"   # editable install: pytest + watchdog + build + ruff
pytest -m core            # fast <3s smoke subset (one test per core function)
pytest                    # full suite (the CI path)
make dist                 # build wheel + sdist into dist/ (for releases)

Releases are cut by tagging vX.Y.Z — see the tag-triggered workflow in .github/workflows/release.yml and the pre-release checklist in docs/release-checklist.md.

Dependency licenses

cairn is MIT-licensed. Its dependencies are all permissive (MIT, BSD, Apache-2.0, MPL-2.0, PSF); see NOTICE for the full list.

The optional [semantic] extra is not installed by default. If you opt into it on Linux, pip resolves torch and its transitive NVIDIA CUDA runtime packages, which carry their own licenses (torch: BSD; NVIDIA CUDA components: NVIDIA EULA / Apache-2.0). The embedding model BAAI/bge-m3 (MIT) is downloaded on demand to ~/.cairn/lib/ and is not redistributed with cairn. None of these are bundled with cairn — they are resolved and accepted by the end user at install time.

Status

Beta — pre-1.0 (v0.6.1). Public surfaces (CLI flags, MCP tool shapes, knowledge-file layout) may still shift before 1.0. Feedback welcome via GitHub issues.

License

MIT — © 2025–2026 Tan Le