Show HN: cairn, a map of all your repos for coding agents

A developer released cairn, an open-source tool that scans every git repo in a folder once and generates a shared map so coding agents can locate the right repo and file without re-exploring. The tool, installed via the Python package cairnmap (Python 3.11+ and git required), produces a roughly 25-token-per-repo always-loaded index plus per-repo cards capped at 800 tokens, and works with Claude Code, Codex, Gemini CLI, and Cursor on Windows, macOS, and Linux. Each relationship carries evidence with file and line plus a trust level of extracted, inferred, or ambiguous, with ambiguous links hidden until confirmed.

A map of all your repos for coding agents. cairn scans every git repo in a folder once, works out how they connect, and gives your agent: - a tiny always-loaded index; - a short card per repo. The agent knows where things live without re-exploring. Cairns are the stacked-stone markers that guide hikers along a trail. cairn leaves small, cheap markers that guide coding agents to the right repo, and then to the right file. Works with Claude Code, Codex, Gemini CLI, and Cursor , on Windows, macOS, and Linux . Coding agents work inside one repo. Real work spans many: a web app, an API, a shared types package, a payments service, a reporting job. Say "add a tip amount to trips end to end" and the agent has to: 1. discover that sibling repos exist; 2. grep through all of them; 3. read a pile of files; 4. guess which service owns the trips table. That costs tokens and turns, and weaker models guess wrong. Hand-maintained "related repos" docs help until they go stale. cairn builds that map from the code itself and keeps it fresh: ~/code/ ~/code/.cairn/ ├── rider-web/ cairn ├── INDEX.md ← ~25 tokens per repo, always loaded ├── trips-svc/ ─────▶ ├── cards/trips-svc.md ← read on demand ≤ 800 tokens ├── payments-svc/ scan ├── workspace.json ← the full graph ├── analytics-etl/ └── authored/ ← your summaries and decisions └── … The index is a few lines, loaded into every session through CLAUDE.md or an equivalent: Workspace repos cairn - admin-console @fleetline/admin-console : Next.js back-office for ops staff; queries trips… · nextjs - analytics-etl: Nightly SQL reporting jobs over trips, payments, drivers… · python - payments-svc payments : Go service that charges completed trips and records weekly payouts · go - trips-svc: FastAPI service owning the trip lifecycle and the trips/trip events tables · fastapi · used by admin-console - ui-kit @fleetline/ui-kit : Shared React components Button, Card · react · used by admin-console used by lists the repos that depend on, call, or reference that one, so a change's blast radius is visible before any card is opened. A card is read only when the agent needs that repo: trips-svc FastAPI service owning the trip lifecycle and the trips/trip events tables. ./trips-svc · python, fastapi · HEAD 1fee22d Relates ← infra: references path trips-svc extracted · infra/docker-compose.dev.yml:3 → admin-console: shares tables trips inferred · admin-console/lib/db.ts:4 → analytics-etl: shares tables trips inferred · analytics-etl/jobs/daily revenue.sql:2 → payments-svc: shares tables trips inferred · payments-svc/internal/charge/charge.go:3 Run test pytest Layout app/ → routes/pages migrations/ → DB migrations Every relationship comes with evidence file and line and a trust level: - extracted : found directly, such as a package dependency or a path reference; - inferred : strong signals, such as a table that only one repo creates; - ambiguous : hidden until you confirm it. You need Python 3.11+ and git. | Tool | Command | |---|---| | uv https://docs.astral.sh/uv/ recommended | uv tool install cairnmap | | pipx | pipx install cairnmap | | run once, no install | uvx --from cairnmap cairn init | | pip | pip install cairnmap | The package is called cairnmap ; the command is cairn . cd ~/code the folder that CONTAINS your repos cairn init scan, then add the index to ./CLAUDE.md asks first cairn install all optional: Codex, Gemini CLI, Cursor, the /cairn skill, the MCP server Open your agent in any repo under that folder. It now knows about every sibling repo. To give each repo a good one-line summary, run /cairn inside your agent. It writes the summaries with cairn set-summary and settles uncertain links. Until then, the index says "no summary yet" for that repo. README text is deliberately kept out of always-loaded context. cairn status repos, relationships, unconfirmed links, missing/stale summaries cairn refresh re-read only repos that changed fast cairn hooks install optional: refresh automatically after each commit/merge php cairn annotate-edge "web- api:shares db" --confirm cairn annotate-edge "shop- blog:shares db" --reject --why "different databases" cairn set-summary payments-svc "Charges completed trips and pays drivers weekly." --alias payments These decisions live in .cairn/authored/ and .cairn/relations.yaml . They survive every re-scan, and you can commit them so your team shares them. cairn install <harness registers cairn's MCP server. Agents can call these tools: | Tool | What it answers | |---|---| | resolve repo | "Which repo is 'the payments service'?" | | repo card | The card for a repo re-scanned first if its HEAD moved | | related | Everything connected to a repo, with evidence | | find across | Which repos expose or use a table, package, or path | | query | Where inside a repo: symbol — file:line from a deep index, else which folders to start in | | refresh | Update the map now | | Signal | Examples | |---|---| | HTTP calls | Next.js routes, Express/Fastify/Hono, FastAPI/Flask, Go net/http, chi, gin, echo and OpenAPI routes, matched with fetch / axios , requests / httpx , and Go http client calls | | gRPC | Go, Python, TypeScript and Java servers matched with their client stubs | | Service names | Calls addressed to a sibling's service name, as Docker and Kubernetes DNS do: http://catalogue , http://carts:8080/carts , .svc.cluster.local , Hostname "payment" | | Pub/sub topics | Kafka, NATS, Redis and RabbitMQ Spring AMQP publishers matched with subscribers trip.completed | | docker-compose | depends on between services built from or named after your repos | | Deploy repos | compose, Kubernetes and Helm files that run your repos' images image: acme/catalogue:1.2 | | Package dependencies | npm workspace: , scoped packages , PyPI, Go modules, Cargo | | Packages inside monorepos | npm/yarn/pnpm, Cargo, go.work and uv workspaces, listed on the card and resolvable by name | | Shared database tables | SQL migrations and queries, Prisma, Drizzle, Supabase, MongoDB Mongoose models, db.collection "x" | | Copies of one app | Repos that share their first commit an app cloned per event or per client : "change one, check the other". The same package name only suggests it | | Path references | ../trips-svc in docker-compose, tsconfig, and other config files | | Documentation | READMEs and docs that mention a sibling repo | | Shared env vars | Specific names read by both sides. These only back up another link; they never make one on their own | Look-alikes are deliberately ignored: - health-check routes; - calls to other companies' APIs; - vague topic names; - .proto files with no implementer; - generic env vars such as PORT ; - localhost , public domains, and URLs in comments; - public images mongo:3.4 and look-alike names catalogue-db is not catalogue ; - a queue that a repo declares but never consumes; - the same schema in two copies of one app copies often use a database each, so no link ; - Firestore's db.collection ... , which looks like MongoDB's. Evaluation workspaces in the test suite keep every one of these at precision 1.0. The map tells an agent which repo to open. A deep index tells it where inside : the query MCP tool answers "where is login handled?" with login — src/auth.py:12 hits and their neighbours, instead of a list of folders. Deep indexes are optional and built per repo with graphify https://github.com/Graphify-Labs/graphify : uv tool install 'cairnmap graphify ' or: pip install 'cairnmap graphify ' cairn deep build trips-svc one repo or --all cairn deep status size, build sha, fresh or stale cairn refresh --deep after changes: rebuild only the stale indexes cairn deep clear trips-svc delete it - graphify always runs --code-only : no LLM, no network, and an allowlisted environment, so no API key reaches it. It writes only to .cairn/deep/<repo / , never into the repo. - cairn answers queries itself from the saved graph, offline, so serving needs no graphify. - Building is never automatic the first build of a large repo can take minutes . When an index falls behind the repo a new commit or an uncommitted edit , query and cairn deep status say so; the card's Deeper section flags new commits. cairn ships a benchmark harness cairn bench . It runs real tasks through headless Claude Code under five conditions, each in a fresh, isolated copy of a multi-repo workspace: | | Condition | |---|---| | A | No map the agent explores | | B | A hand-written "related repos" doc | | C | cairn's index only | | D | Index + repo cards | | E | D + cairn's MCP server | Tasks cover: - orientation: "who owns the trips table?"; - localization: "which files change to add a tip amount end to end?"; - cross-repo impact: "what breaks if drivers.license no is renamed?"; - control: questions answerable within one repo. Answers are graded deterministically on the files and facts they must name. Results 2026-10-06 : 840 runs over four workspaces, two of them real open-source systems: Sock Shop 9 microservice repos; cairn's newest link types were developed on it and the Supabase JS client family 6 repos, held out: never used to tune cairn . 28 tasks, 3 runs per cell, Haiku 4.5 and Sonnet 5.5. A result is called significant only after Holm adjustment. | Per task, cairn INDEX C | Haiku 4.5 | Sonnet 5.5 | |---|---|---| | Fresh tokens vs no map | -19% significant | -10% n.s. | | Cost vs no map | -25% n.s. after adjustment | -12% n.s. | | Cost vs a hand-written doc | -6% n.s. | -12% significant | | Cost vs no map, Sock Shop only | -27% n.s. | -26% borderline, adjusted p = 0.055 | What this shows: - cairn tends to make cross-repo work cheaper : fewer fresh tokens for Haiku, and cheaper than a hand-written related-repos doc for Sonnet. The largest raw savings were on Sock Shop. - It doesn't measurably raise success. Sonnet answers 99-100% of these tasks in every condition; Haiku rises from 86% to 93% with the MCP server, which isn't significant. - It isn't a win everywhere. On fleetline, Sonnet cost 7-10% more with cairn than without n.s. ; the held-out Supabase effects are small and not significant. - Correction: our first, smaller run 2026-10-05 reported Haiku reaching 100% with the INDEX. With more runs that doesn't replicate 89-92%, the same as no map . Methods, every table with 95% intervals, paired Wilcoxon tests raw and Holm-adjusted , the regressions, and the held-out results: bench/published/2026-10-06-real-world.md https://github.com/Moe1177/cairn/blob/main/bench/published/2026-10-06-real-world.md . The first run is kept at 2026-10-05-shopverse-fleetline.md https://github.com/Moe1177/cairn/blob/main/bench/published/2026-10-05-shopverse-fleetline.md . Run the benchmarks yourself from a source checkout. They use your Claude usage. cairn bench bench/suites/sockshop --runs 3 --model haiku fetches the pinned repos once cairn bench bench/suites/shopverse --conditions A,C --tasks gift-message cairn bench bench/suites/sockshop --resume bench/results/<stamp .jsonl after a usage limit cairn walks each repo once, reads each file once, and scans repos in parallel. A refresh re-reads only repos whose HEAD or working tree changed, and asks git one question per unchanged repo. On a synthetic workspace of 200 repos and 50,000 files Windows 11, 12 cores : | | 0.3 | 0.4 | |---|---|---| | First scan | 156 s | 53 s | | Refresh, nothing changed | 15 s | 5.4 s | Most of a refresh on Windows is git process start-up; Linux and macOS start processes faster. Reproduce with uv run python bench/perf scan.py --out <dir . cairn treats every scanned repo as untrusted input. It: - never modifies your repos, apart from the opt-in hooks and Cursor's --per-repo rule both marked blocks, removed cleanly ; - never opens .env files, private keys, or credential files, and never reads through a symlink or junction inside a repo; - never runs code from a repo: its git calls turn off fsmonitor, hooks, and the repo's own filters. It also: - redacts common secret formats from every stored snippet, and stores git remotes without credentials; - keeps README text out of always-loaded context. Repo names that do appear are flattened and capped, so they can't inject instructions or break cairn's blocks. cairn makes no network calls and collects no telemetry . cairn bench is the only feature that runs another program that does the claude CLI . See SECURITY.md https://github.com/Moe1177/cairn/blob/main/SECURITY.md for the threat model and how to report a vulnerability. | Command | What it does | |---|---| | cairn init | Scan, then offer to add the index to Claude Code | | cairn scan --full --verbose | Map every repo under the folder into .cairn/ | | cairn refresh --deep | Re-read only repos whose HEAD or working tree changed --deep : also rebuild stale deep indexes | | cairn deep build REPO…\|--all\|--stale -w PATH | Build graphify code indexes so query answers with file:line optional extra | | cairn deep status / cairn deep clear REPO… | List deep indexes fresh or stale / delete them | | cairn status | What cairn knows, unconfirmed links, missing or stale summaries | | cairn annotate-edge KEY --confirm\|--reject --why TEXT | Settle a relationship | | cairn set-summary REPO TEXT --alias NAME | Save a summary - reads stdin | | cairn install <claude\|codex\|gemini\|cursor\|all | Load cairn into an agent harness | | cairn uninstall <name\|all | Remove it again | | cairn hooks install\|uninstall | Opt-in git hooks that refresh after commits and merges | | cairn serve | The MCP server harnesses start it for you | | cairn bench SUITE | Run the benchmark harness | | cairn doctor | Check git, Python, the map, write access, harnesses and graphify; exits 1 on a failure | | cairn --install-completion | Tab completion for your shell bash, zsh, fish, PowerShell | | cairn --version | Versions of cairn, Python, the platform, and mcp | Exit codes: 0 means success, 1 an error one line on stderr , and 2 a usage error. | Path | What it is | |---|---| | <folder /.cairn/INDEX.md | One line per repo: name, aliases, summary, stack | | <folder /.cairn/cards/<repo .md | One card per repo | | <folder /.cairn/workspace.json | The full graph | | <folder /.cairn/cache/ , logs/ , .lock | Scan cache, last scan log, lock file | | <folder /.cairn/relations.yaml , authored/ | Yours: aliases, manual links, summaries, decisions | | <folder /CLAUDE.md | A marked block holding the index cairn install claude | | ~/.claude/skills/cairn/ and Claude's user MCP config | /cairn skill and MCP server | | ~/.codex/AGENTS.md , config.toml , skills/cairn/ | Codex pointer, MCP server, skill | | ~/.gemini/GEMINI.md , settings.json , commands/cairn.toml | Gemini CLI pointer, MCP server, command | | ~/.cursor/mcp.json , commands/cairn.md | Cursor MCP server and command | | <repo /.git/hooks/post-commit , post-merge | Only with cairn hooks install | | ~/.cairn/registry.json , backups/ | Mapped workspaces; one private backup of each config file cairn first edited | cairn only edits its own key or marked block in other tools' files, and refuses to touch a file it can't parse. cairn uninstall all harness entries, skills, commands, Cursor rules cairn hooks uninstall if you installed hooks uv tool uninstall cairnmap or: pipx uninstall cairnmap Then delete <folder /.cairn/ and ~/.cairn/ . | Symptom | Fix | |---|---| | Something seems off | Run cairn doctor : it checks each dependency and says what to fix | | "No git repos found under …" | Run cairn from the folder that contains your repos | | "… is inside the git repository …" | Same: run from the parent folder, not inside a repo | | "git not found on PATH" warning | Install git; without it, remotes, HEAD and caching are off | | "another cairn process is still updating this workspace" | A scan or hook refresh is running; retry in a moment | | An agent says it can't find the workspace | Run cairn init in the workspace folder, then restart the agent session | | cairn install codex/gemini/cursor refuses a config | That file isn't valid TOML/JSON; fix it and re-run cairn never guesses | | Hooks did nothing | cairn hooks install lists the repos it skipped and why | 1. ✅ Core map, precision pass, MCP server, harness integrations, freshness, benchmarks, release hardening 0.1 . 2. ✅ HTTP, gRPC, pub/sub, compose and env-var relationships; packages inside monorepos 0.2 . 3. ✅ Deep per-repo queries via graphify https://github.com/Graphify-Labs/graphify 0.3 . 4. ✅ Efficiency: 3x faster scans, faster and more reliable CI, cairn doctor , shell completion, and "used by" on INDEX lines 0.4 . 5. ✅ Real-world reach service DNS, deploy repos, RabbitMQ and benchmarks on real open-source workspaces with significance testing 0.5 . 6. More harnesses in the benchmark Codex , and more ecosystems. Issues and pull requests are welcome. See CONTRIBUTING.md https://github.com/Moe1177/cairn/blob/main/CONTRIBUTING.md for setup and checks, and the changelog https://github.com/Moe1177/cairn/blob/main/CHANGELOG.md for what's new. By participating you agree to the code of conduct https://github.com/Moe1177/cairn/blob/main/CODE OF CONDUCT.md . cairn is licensed under the Apache License 2.0 : use it, modify it, and ship it, commercially too. Keep the license and the NOTICE https://github.com/Moe1177/cairn/blob/main/NOTICE file with any redistribution. Full text: LICENSE https://github.com/Moe1177/cairn/blob/main/LICENSE . Runtime dependencies and their licenses: | Package | License | |---|---| | typer https://github.com/fastapi/typer | MIT | | pydantic https://github.com/pydantic/pydantic | MIT | | PyYAML https://github.com/yaml/pyyaml | MIT | | pathspec https://github.com/cpburnz/python-pathspec | MPL-2.0 used unmodified as a library | | mcp https://github.com/modelcontextprotocol/python-sdk | MIT |