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. Generate AGENTS.md (run once)
carto init

# 3. Keep it live while you work
carto watch

Leave carto watch running in a background terminal. Every file save updates AGENTS.md automatically.

Commands

| Command | What it does | |---------|-------------| | carto init | Detect stack, generate AGENTS.md, install git hook | | carto watch | Watch files, update AGENTS.md on every save | | carto sync | One-time refresh, no watcher | | 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, when you add Carto to a project
• watch — every work session, leave it running
• sync — 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.