cartographer ⟶ rag over codebases
Cartographer
liveAsk questions about a TypeScript codebase and get answers with citations to exact files and lines.
Tech stack: RAG, tree-sitter, Chroma, Express, VPS
summary
Cartographer is a retrieval-augmented system for querying TypeScript codebases in natural language, answering with citations to exact file paths and line numbers.
It leans on how code is actually structured. tree-sitter chunks the source into whole functions, methods, and classes instead of arbitrary text windows, and Claude expands the query before embedding so that asking "how do I deploy" still finds code that talks about "deployment". It has since grown cross-project search over multiple indexed repos and a code-change impact analyzer.
It runs as a real deployment: an Express backend on a DigitalOcean VPS behind Caddy and PM2, with a Vercel frontend.
features
AST-aware chunking
tree-sitter extracts functions, methods, and classes as atomic units — far better than naive text splitting for code.
Query expansion
Claude rephrases the question before embedding, bridging the gap between how people ask and how code is written.
Cited answers
Every answer points back to exact file paths and line numbers.
Cross-project search
Query several indexed repos at once, with reciprocal-rank-fusion merging across projects.
Impact analysis
Trace the blast radius of a code change by combining static and embedding-based semantic dependency analysis.
Real deployment
Express, PM2, and Caddy on a DigitalOcean VPS, with a Vercel frontend.
architecture
Ingestion clones a repo, chunks it with tree-sitter, embeds the chunks, and stores them in Chroma. Queries are expanded by Claude, embedded, and retrieved; multi-project retrieval merges results with reciprocal rank fusion. An Express server exposes /query, /projects, and /impact. Deployed on a DigitalOcean VPS (PM2 + Caddy) with a Vercel frontend.
changelog
- Feature: Shareable impact links: generate a read-only URL for a code-change impact analysis.
- Feature: Code-change impact analysis: a cartographer impact CLI and endpoint that combine static and embedding-based semantic dependency analysis with risk scoring.
- Feature: Cross-project search: query multiple indexed repos at once with reciprocal-rank-fusion merging, backed by an incremental multi-project indexer.
- Improvement: Frontend redesign with a paper/ink design system and loading states.
- Feature: Initial release: natural-language RAG over TypeScript codebases with AST-aware chunking via tree-sitter, query expansion via Claude, Chroma vector search, and cited answers.