carto

Maps your codebase so AI stops guessing. Your code changes. AGENTS.md updates. Every AI always knows.

npm install -g carto-md

Carto auto-generates and maintains your AGENTS.md — the standard file every AI coding tool reads for project context. Every time you save, your routes, models, functions, and dependencies are extracted and kept current.

---

The problem

AI coding tools are blind to your actual project. Every session starts from zero.

• Claude hallucinates your schema
• Copilot suggests the wrong field names
• Kiro asks what framework you're using
• You rebuild context manually, every time

AGENTS.md fixes this — a file in your project root that every AI tool reads. But it's static. You write it manually. It gets stale the moment your code changes.

Carto makes it live.

---

Proof — cal.com (800k lines)

Same task, two Claude sessions: "Add a notes field to the booking model."

Without AGENTS.md:

• Wrong API route: suggested POST /api/bookings → actual is POST /v2/bookings
• Wrong handler: suggested handleNewBooking.ts → not the creation path
• Wrong file paths: pointed to v1 API (apps/api/v1/...) → v1 is legacy
• Wrong tRPC file: bookings.tsx → actual is bookings/_router.tsx
• Field list: ~15 fields guessed → missing 20+ real fields
• Couldn't proceed without follow-up: "Want me to write the exact diffs once you confirm the codebase location?"

With AGENTS.md (generated by Carto):

• Correct API route: POST /v2/bookings ✅
• Correct controller path ✅
• Correct tRPC file ✅
• All 35+ booking fields returned accurately ✅
• Answered in one shot. No follow-up needed.

4 wrong file paths → 0. 20 missing fields → 0. Zero follow-up clarifications.

Not smarter AI. The same AI with accurate facts.

Stress tested on cal.com (5,018 files): 87% route coverage, 100% model field accuracy, import graph with zero phantom links.

---

Know what breaks before you break it

Most production bugs aren't logic errors. They're "I didn't know X depended on Y."

carto impact makes that invisible knowledge visible — before you touch anything.

carto impact app/models.py

# Impact analysis: app/models.py
#
# Imported by:
#   → app/main.py
#   → app/rules.py
#   → app/scoring.py
#   → app/aws_collector.py
#   → tests/conftest.py
#
# Routes affected:
#   → POST /analyze
#   → GET /history
#   → POST /simulate
#   → ... 12 more
#
# Risk: HIGH — 5 files depend on this

No AI. No cloud. Runs in under a second. Locally, from your import graph.

Make it a habit: before touching any file, run carto impact first. 10 seconds. Could save hours.

---

Why not just paste your code?

Context windows are large now. But pasting code means:

• You decide what's relevant — you're often wrong
• AI sees a snapshot, not your live state
• Bigger context ≠ better context

Carto gives AI the map. You give AI the problem. Different jobs.

---

How it works

You save a file
      ↓
Carto extracts routes, models, functions, env vars
      ↓
AGENTS.md updated in 300ms
      ↓
Cursor, Copilot, Kiro, Codex, Claude — all read current truth

---

Install

npm install -g carto-md

Or run without installing:

npx carto-md init

---

Usage

# 1. Go to your project
cd your-project

# 2. Run once — like git init
carto init

That's it. Carto installs a git hook. Every git commit syncs AGENTS.md automatically — no watching, no manual runs, nothing to remember.

Want live updates on every file save too? Run carto watch in a background terminal.

---

Commands

Command	What it does
carto init	Detect stack, generate AGENTS.md, install git hook — auto-syncs on every commit
carto watch	Live updates on every file save — optional, for between commits
carto sync	One-time manual refresh
carto impact <file>	Show blast radius before touching a file
carto remove	Remove AGENTS.md and .carto/ from this project
carto --version	Show version

When to use each:

• init — once per project, sets everything up
• watch — optional, if you want updates between commits
• sync — if you skipped watch and need a fresh snapshot
• impact — before editing anything critical

---

Works with

Language	Frameworks
Python	FastAPI, Pydantic
JavaScript	Express, Next.js
TypeScript	Express, Next.js, Prisma
R	Plumber, Shiny
HTML	fetch() calls

More languages via community — open an issue or see CONTRIBUTING.md.

---

What gets extracted automatically

• API routes — FastAPI, Express, Next.js App Router
• Data models — Pydantic, Prisma
• Function signatures — across all files
• Dependencies — from package.json / requirements.txt
• Environment variable names — never values
• Frontend API calls — from fetch() patterns
• Import graph — which files depend on which
• Database tables

---

What Carto never touches

Your manual sections — architecture decisions, active bugs, business rules, coding conventions — stay yours forever. Carto only rewrites between its own markers:

<!-- CARTO:AUTO:START -->
... auto-generated content ...
<!-- CARTO:AUTO:END -->

Your manual notes here. Never touched.

---

What Carto fixes

Carto fixes factual hallucination about your own project:

• AI guessing wrong routes → fixed
• AI guessing wrong field names → fixed
• AI assuming wrong framework → fixed
• AI guessing wrong DB schema → fixed

What Carto does not fix: AI reasoning badly, wrong implementation logic, misunderstanding what you want. Carto makes AI accurate about your project. Not smarter. Accurate. Different thing.

---

AI tools that read AGENTS.md

Drop the file in your project root. Each tool picks it up via its own context config:

• Cursor — via context rules
• GitHub Copilot — via workspace instructions
• Kiro — natively
• Codex — natively
• VS Code — via workspace context
• Gemini CLI — natively
• Devin — natively
• Jules — natively

---

What it does NOT do

• No cloud. No servers. No telemetry. No tracking.
• Your code never leaves your machine.
• No paid tiers. Free forever. MIT license.

---

Security

Carto never writes secrets into AGENTS.md. .cartoignore blocks .env files, secret files, key files, and credential files by default. The sanitizer strips API key patterns from extracted code.

---

Contributing

Python, JS/TS, and R today. Want Go, Ruby, Django, Rails? Open an issue — or read CONTRIBUTING.md to add it yourself.

---

Origin

I was building Emfirge — a cloud security agent for AWS.

To make the AI inside Emfirge understand infrastructure, I wrote a module called cartography.py. It mapped AWS resources, built a graph of how they connected, and wrote it into a structured map. The AI stopped hallucinating. It worked with accurate facts — not guesses.

Halfway through, I switched AI tools. Opened a new session. Had to explain everything again from scratch.

I thought: I just built a cartography system so AI can understand infrastructure. Why doesn't this exist for codebases?

Carto is that. Same insight, different domain.

---

License

MIT — free forever.

---

Built because AGENTS.md won. Someone had to keep it alive.