A private, local-first code intelligence engine for Claude Code. Search your entire codebase by meaning — not just keywords. Like having your own private mgrep, running entirely on your machine.
Claude Cartographer maps your entire project — every function, class, method, and export — into a local SQLite database with semantic embeddings. When Claude needs to understand your code, it queries the map instead of reading full files, saving 95%+ tokens on typical operations. Everything runs locally. No data leaves your machine.
# Clone and install
git clone https://github.com/pect0ral/claude-cartographer.git
cd claude-cartographer
./setup.sh /path/to/your/project
# Start using (from your project directory)
.claude-map/bin/claude-map find UserProfile # Quick name search
.claude-map/bin/claude-map query "authentication handlers" # Semantic search
.claude-map/bin/claude-map stats # View statistics- Initial Mapping — Scans your project, extracts all classes, functions, methods, and exports using language-aware parsers
- 3-Tier Storage — Stores components at three detail levels: compact (50 tokens), summary (200 tokens), and full (compressed)
- Semantic Embeddings — Generates local ONNX embeddings (all-MiniLM-L6-v2) for meaning-based search
- Real-Time Updates — Claude Code hooks automatically queue file changes as you edit; the map stays current
- Hybrid Search — Queries combine semantic similarity (70%) with keyword matching (30%) for accurate results
- Token-Efficient Responses — Returns precise locations and signatures using 50–200 tokens instead of thousands
- Natural language queries: "authentication handlers", "database helper functions"
- ONNX-based embeddings (all-MiniLM-L6-v2), runs entirely on your machine
- Hybrid scoring: 70% semantic + 30% keyword relevance
- Graceful fallback to keyword-only search when semantic dependencies are unavailable
- Python — Full AST parsing with type hints, decorators, async/await
- JavaScript/TypeScript — Classes, functions, interfaces, React components, JSX
- Go — Structs, interfaces, functions, methods, goroutines
- Ruby — Classes, modules, methods, mixins
- Templates — Jinja2, EJS, Handlebars, SQL schemas
- 3-tier system: compact (50 tokens), summary (200 tokens), full (compressed)
- SQLite with FTS5 full-text search, WAL mode, memory mapping
- Self-contained in
.claude-map/— nothing touches your project files
- Hooks — Automatically queue file updates on Edit/Write operations
- Skills — Claude learns to search the map before reading files
- Commands —
/mapfor manual operations (init, update, stats, find) - Permissions — Auto-configured for seamless CLI access
- UV package manager —
curl -LsSf https://astral.sh/uv/install.sh | sh - Python 3.10+ — UV will download if needed
- macOS or Linux (Windows not currently supported)
# Full setup: install + initialize map + benchmark
./setup.sh /path/to/your/project
# Or step-by-step
python install.py /path/to/your/project
cd /path/to/your/project
.claude-map/bin/claude-map init# Updates source code, recreates venv with fresh dependencies
python install.py --update /path/to/projectpython install.py --force /path/to/projectpython install.py --uninstall /path/to/project
python install.py --uninstall --keep-db /path/to/project # Backup database| Command | Purpose | Key Options |
|---|---|---|
find <name> |
Quick name search | -l/--limit, -o/--offset, -q/--quiet |
query "<text>" |
Semantic + keyword search | -t/--max-tokens, --no-semantic, -o/--offset, -f/--format, -q/--quiet |
show <file> |
File structure | -q/--quiet |
exports |
List public API | -l/--limit, -o/--offset, -q/--quiet |
stats |
Database stats | -f/--format |
session |
Token savings | -v/--verbose, --lifetime, -f/--format |
init [path] |
Initialize mapping | -w/--workers, --no-mp, --no-embeddings, --watch |
update |
Incremental update | -w/--workers, --no-mp, --rebuild-embeddings |
watch |
Auto-update on changes | -d/--debounce |
optimize |
DB maintenance | — |
benchmark |
Performance test | --verbose/--quiet, -f/--format |
# Search by name (fastest)
.claude-map/bin/claude-map find UserProfile
# Semantic search (finds by meaning)
.claude-map/bin/claude-map query "authentication handlers"
# Keyword-only search (skip embeddings)
.claude-map/bin/claude-map query "auth" --no-semantic
# Token-limited search
.claude-map/bin/claude-map query "database helpers" -t 5000
# File structure without reading the file
.claude-map/bin/claude-map show src/auth.py
# Initialize without generating embeddings
.claude-map/bin/claude-map init --no-embeddings
# Regenerate all embeddings after model update
.claude-map/bin/claude-map update --rebuild-embeddingsWhen results are truncated, use --offset / -o to paginate:
.claude-map/bin/claude-map find User -o 20 # Results 21-40
.claude-map/bin/claude-map query "auth" -o 50 # Results 51+| Feature | Claude Cartographer | mgrep |
|---|---|---|
| Runs locally | Yes | No (cloud) |
| Your data stays private | Yes | Depends |
| Semantic search | Yes (ONNX) | Yes |
| Keyword search | Yes (FTS5) | Yes |
| Claude Code integration | Native (hooks, skills) | None |
| Token optimization | Yes (95%+ savings) | N/A |
| Real-time updates | Yes (hooks) | Manual |
| Cost | Free (MIT) | Paid |
| Operation | Traditional (tokens) | Cartographer (tokens) | Savings |
|---|---|---|---|
| Find component | 15,000 | 200 | 98.7% |
| File dependencies | 25,000 | 500 | 98.0% |
| List exports | 30,000 | 1,000 | 96.7% |
| File summary | 20,000 | 800 | 96.0% |
| Call chain | 40,000 | 1,500 | 96.3% |
Overall: 95–98% token reduction
- Python — Full AST parsing with type hints, decorators
- JavaScript/TypeScript — Classes, functions, interfaces, React components
- Go — Structs, interfaces, functions, methods
- Ruby — Classes, modules, methods
- Templates — Jinja2, EJS, Handlebars
We'd love your help! Areas where contributions are especially welcome:
- Language support — Rust, Java/Kotlin, C/C++, Swift, PHP, Terraform/HCL
- Parser improvements — Better signature compression, smarter dependency extraction
- Token-saving techniques — Semantic summarization, context-aware snippets, caching strategies
- Performance — Parallel parsing, incremental updates, memory reduction
- Fork the repository
- Check Issues for
good-first-issueorhelp-wanted - Submit a pull request
Our goal: maximize the value of your Claude subscription by minimizing token waste. Every feature should serve this mission.
MIT License — Copyright (c) 2025 Breach Craft
See LICENSE for details.
Created by Mike Piekarski (mp@breachcraft.io) Founder, Breach Craft