🦀 Crabmap

Crabmap builds a durable, queryable knowledge graph of any Rust project. Give it to an AI agent — it understands the entire codebase without reading files one by one.

Think of it as a satellite map of your Rust codebase, while LSP (rust-analyzer) gives you a microscope for individual symbols.

✨ Why Crabmap?

🚀 Quick Start

# Install
cargo install crabmap

# Index a project
crabmap index /path/to/rust/project
# ✓ indexed 9089 nodes, 14355 edges in 168 files

# Get an AI-ready architecture map
crabmap nav map

# Search for anything
crabmap query search "handle_connection"

# Explore interactively in the browser
crabmap serve

📦 Commands

crabmap index — Build the graph

crabmap index .                           # Index current project
crabmap index --all .                     # Discover & index all Cargo projects
crabmap index --no-tests                  # Skip test files
crabmap index --output custom.json.gz     # Custom output path (gzipped)

crabmap query — Ask questions

crabmap query stats                       # Node/edge counts
crabmap query search "config"             # Fuzzy text search
crabmap query symbol main                 # Inspect a symbol
crabmap query callees main --depth 3      # What does main call?
crabmap query callers load_config         # Who calls this?
crabmap query impact Runtime --depth 2    # Full dependency impact
crabmap query path main load_config       # Shortest call path

crabmap nav — AI-oriented navigation

crabmap nav map           # Token-budgeted project overview (for LLMs)
crabmap nav guide         # Entry points + call chains
crabmap nav clusters      # Feature clusters by file
crabmap nav quality       # Graph confidence score
crabmap nav health        # Cycles, god modules, dead code

crabmap analyze — Static analysis

crabmap analyze deps      # Module dependency matrix
crabmap analyze fanout    # File-level fan-in / fan-out
crabmap analyze tests     # Test impact candidates
crabmap analyze hotspots  # Git churn hotspots
crabmap analyze diff      # Graph diff vs git base

crabmap serve — Web UI

crabmap serve                         # Index + serve
crabmap serve --graph graph.json.gz   # Serve a pre-built graph
crabmap serve --watch                 # Auto-reindex on file changes

crabmap config — API Keys (for LLM features)

crabmap config --api-key sk-... --model gpt-4

🌐 Web UI

Launch crabmap serve and open http://127.0.0.1:7878:

• Graph visualization — force-directed layout, color-coded by node/edge kind
• Interactive exploration — click nodes to expand, drag to rearrange
• Edge filtering — toggle relationship types (calls, declares, uses_type, …)
• Detail drawer — inspect symbols, files, edges
• Chinese UI — full zh-CN interface

🧪 Tested On

All three projects indexed with zero warnings.

🔧 How It Works

1. cargo metadata → discovers packages, targets, source files
2. syn AST walk → extracts structs, enums, functions, methods, impls, macros…
3. Call resolution → same-module priority, method-to-trait-impl matching
4. rust-analyzer enrichment (optional) → LSP call hierarchy for confirmed edges
5. MIR lowering (optional) → rustc MIR for dispatch sites
6. Graph persistence → gzip-compressed JSON (14× smaller than raw)

📄 Graph Format

The output is a single JSON file (gzipped by default):

{
  "schema_version": 2,
  "project": { "root": ".", "packages": […] },
  "nodes": [
    { "id": "function:crabmap::run", "kind": "function", "name": "run", … }
  ],
  "edges": [
    { "from": "function:crabmap::main", "to": "function:crabmap::run",
      "kind": "calls", "source": "ast", "certainty": "definite" }
  ]
}

🛠 Building from Source

git clone https://github.com/trtyr/crabmap.git
cd crabmap
cargo build --release
./target/release/crabmap --version
# crabmap 0.1.2 (abc1234 2026-05-21)

Requires Rust ≥ 1.85 (edition 2024).

📁 Project Layout

src/
├── main.rs          # CLI entry & command dispatch
├── cli.rs           # clap argument definitions
├── analyzer.rs      # AST indexer (syn walk)
├── query.rs         # Graph traversal & search
├── model.rs         # Core data model
├── store.rs         # Gzip JSON load/save
├── web.rs           # Embedded HTTP server
├── semantic.rs      # rust-analyzer enrichment
├── mir.rs           # MIR lowering
├── ai.rs            # AI nav commands
├── config.rs        # Global config (~/.config/crabmap/)
├── term.rs          # ANSI terminal colors
├── health.rs        # Architecture risk detection
└── …

web/
├── index.html
├── styles/          # CSS (dark theme)
└── src/             # JS (microkernel architecture)

skills/
└── crabmap.md     # AI agent usage guide (skill file)

📝 License

MIT