codesynapse

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="assets/logo-light.svg"> <img src="assets/logo-light.svg" alt="codesynapse" height="60"> </picture> <br/> **Code intelligence MCP server — gives AI coding assistants architecture-level knowledge of your codebase.** [](https://github.com/sohilladhani/codesynapse/actions/workflows/ci.yml) [](https://crates.io/crates/codesynapse-cli) [](LICENSE) [](https://www.rust-lang.org) [Quick Start](#quick-start) · [MCP Tools](#mcp-tools) · [Languages](#language-support) · [Configuration](#configuration) · [Uninstall](#uninstall) · [Troubleshooting](#troubleshooting) · [Contributing](#contributing) <br/> <a href="https://www.producthunt.com/products/codesynapse?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-codesynapse" target="_blank" rel="noopener noreferrer"><img alt="codesynapse - Code graph as MCP tools makes your AI stops hallucinating | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1180306&theme=light&t=1782391600666"></a> </div> --- AI coding tools answer questions about individual files well. They cannot reason about *architecture* — class hierarchies, call chains, blast radius of a change, which module owns a concept. `grep` and file search return noise, not signal. Codesynapse fixes this. It builds a structural knowledge graph from your source code (nodes = classes, functions, files; edges = calls, extends, implements, contains), merges graphs from multiple modules into a single global graph, and exposes **32 MCP tools** backed by hybrid BM25 + dense vector search. Every session with Claude Code or Cursor starts with full graph context — not a blank slate. Runs entirely local. No GPU, no cloud APIs, no infrastructure. --- ## Demo <img src="assets/demo.gif" alt="codesynapse demo — module add, module list, query" width="100%"> <!-- To regenerate: install vhs (https://github.com/charmbracelet/vhs) then run: vhs assets/demo.tape --> --- ## Why codesynapse? | | Python graphify | graphify-rs | semble | code-review-graph | codegraph | cbm | Sourcegraph Cody | continue.dev | **codesynapse** | |---|---|---|---|---|---|---|---|---|---| | **Language** | Python | Rust | Python | Python | TypeScript | C | Cloud | VS Code ext. | **Rust** | | **MCP tools** | ✗ | ✗ | 2 | 30 | 10 | ~8 | ✗ | ✗ | **32** | | **Structural graph** | Partial | General KG | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | **✓** | | **Blast radius** | ✗ | ✗ | ✗ | ✓ | ✓ | ✗ | ✓ | ✗ | **✓** | | **Hybrid BM25 + dense** | ✗ | BM25 only | ✓ | Optional | ✗ (FTS5) | ✗ | ✓ | ✗ | **✓** | | **Fully local** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | **✓** | | **No cloud API needed** | ✓ | ✓ | ✓ | ✗ (semantic) | ✓ | ✓ | ✗ | ✗ | **✓** | | **Multi-module graph** | ✗ | ✗ | ✗ | ✓ | ✓ | ✗ | ✓ | ✗ | **✓** | | **Cross-module hierarchy** | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✓ | ✗ | **✓** | | **File reads eliminated** | — | — | — | — | 100% | partial | — | — | **100%** | | **No telemetry by default** | ✓ | ✓ | ✓ | ✓ | ✗ (opt-out) | ✓ | ✗ | ✗ | **✓ (opt-in)** | | **Runtime** | Python | Rust | Python | Python | Node.js | C binary | Cloud | Node.js | **Rust binary** | **[codegraph](https://github.com/Tgedin/codegraph)** is the closest alternative — TypeScript, local, 10 MCP tools, blast radius, multi-module. Key gap: lexical FTS5 search only (no dense embeddings), so synonym and concept queries miss results that BM25+dense RRF catches. **[cbm (codebase-memory-mcp)](https://github.com/DeusData/codebase-memory-mcp)** is a C binary with a SQLite graph store — fast cold-start indexing (no embedding pass), but no hybrid search and requires multiple file reads per query (8–10 observed vs 0 for codesynapse). **semble** uses the same Model2Vec + BM25 + RRF search stack but is search-only — no structural graph, no blast radius, no hierarchy. **code-review-graph** has graph + MCP but is Python and requires a cloud API for semantic search. **graphify-rs** is the Rust rewrite of the original Python graphify tool — general-purpose knowledge graphs, not MCP-native or code-intelligence-focused. Codesynapse is the Rust rewrite of [Python graphify](https://github.com/safishamsi/graphify) with full MCP integration, structural graph analysis, and zero cloud dependencies. --- ## Benchmarks Measured on real open-source repos (redis, tokio, django-framework). Docker, `--cpus=4 --memory=8g`, 3 runs median. Full methodology and per-question scores: [BENCHMARKS.md](BENCHMARKS.md). Competitors: [codegraph](https://github.com/Tgedin/codegraph) (TypeScript, SQLite FTS5), [cbm/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) (C, SQLite graph store, no embeddings). **Indexing speed** — cold-start index time: | Repo | codesynapse | codegraph | cbm | |------|-------------|-----------|-----| | redis (C, ~700 files) | **3.8s** | 60.8s | 5.9s | | tokio (Rust, ~900 files) | **4.6s** | 36.8s | 2.0s | | django-framework (Python, ~2k files) | **17.5s** | 306s | 12.4s | codesynapse indexes **8–17× faster than codegraph**. cbm is faster than codesynapse on indexing because it skips the embedding pass — but that means every query requires multiple file reads (8–10 observed), while codesynapse queries return zero file reads. **Query accuracy** (Claude judge, 0–10 scale, on questions where the answer symbol name doesn't appear in the question — e.g. "what handles access control?" → `IsAuthenticated`): | | codesynapse | codegraph | cbm | baseline | |---|---|---|---|---| | avg score | **8.9** | 9.0 | 8.7 | 8.6 | | file reads per query | **0** | 0 | 8–10 | — | Scores are comparable across tools. The codesynapse advantage is operational: zero file reads means lower token cost per session and no context blowout on large codebases. codegraph's lexical-only search (SQLite FTS5) should struggle on synonym queries, but Claude compensates with follow-up tool calls — so both reach similar scores via different paths. --- ## How it works ```mermaid flowchart TD A[("Source code\n(any repo)")] -->|parallel tree-sitter AST\n30+ languages| B["per-module graph.json"] B -->|global_add — prefix node IDs, merge| C[("global-graph.json\n~/.codesynapse/")] C -->|embed_global_graph\npotion-code-16M · CPU-only · mtime-gated| D[("embeddings.json\n~/.codesynapse/")] C & D --> E[["MCP server\n32 tools · hybrid BM25 + dense RRF"]] E --> F["Claude Code · Cursor · OpenCode\nCodex CLI · Hermes · Kiro · any MCP client"] style A fill:#f6f8fa,stroke:#57606a,color:#24292f style B fill:#ddf4ff,stroke:#54aeff,color:#0550ae style C fill:#dafbe1,stroke:#4ac26b,color:#1a7f37 style D fill:#fff8c5,stroke:#d4a72c,color:#4d2d00 style E fill:#ede9fe,stroke:#8957e5,color:#512a97 style F fill:#ffeef8,stroke:#bf3989,color:#6e1e5c ``` **Key design choices:** | Decision | Reason | |---|---| | Hybrid BM25 + dense RRF | BM25 handles symbol names precisely; dense closes the synonym gap. RRF fusion gives best of both. | | Model2Vec `potion-code-16M` | Static embeddings — no forward pass at query time, ~1.5ms queries, CPU-only, 64 MB model. | | Sled embedded DB | Zero-dependency, file-based, fast random access by node ID. No server process. | | Tree-sitter AST extraction | Grammar coverage across 30+ languages. No language server or build system required. | | Per-module → global merge | Enables cross-module blast radius and hierarchy without loading all modules into memory. | | Mtime-gated embedding regen | Embeddings only regenerated when `global-graph.json` is newer. Zero overhead for unchanged graphs. | --- ## Language support | Group | Languages | |---|---| | **Systems** | Rust, C, C++, Go, Zig, Fortran, Verilog | | **JVM** | Java, Kotlin, Scala, Groovy | | **Web / Frontend** | JavaScript, TypeScript, Svelte, Vue, PHP | | **Scripting** | Python, Ruby, Lua, Bash, PowerShell | | **Mobile / Apple** | Swift, Objective-C, Dart | | **Functional** | Haskell, Elixir, Racket, Julia | | **Other** | SQL, C#, CMake, Pascal | --- ## Installation **Prerequisites:** - ~500 MB free disk (graph store + model, downloaded on first `setup`) - Internet connection on first run (model download only) **Option A — One-liner** Linux / macOS: ```bash curl -fsSL https://raw.githubusercontent.com/sohilladhani/codesynapse/master/install.sh | sh ``` Windows (PowerShell): ```powershell irm https://raw.githubusercontent.com/sohilladhani/codesynapse/master/install.ps1 | iex ``` Or download a specific binary from [releases](https://github.com/sohilladhani/codesynapse/releases/latest): | Platform | Binary | |---|---| | Linux x86_64 | `codesynapse-linux-x86_64` | | macOS Apple Silicon | `codesynapse-macos-aarch64` | | Windows x86_64 | `codesynapse-windows-x86_64.exe` | ```bash chmod +x codesynapse-* sudo mv codesynapse-* /usr/local/bin/codesynapse ``` **Option B — Package managers** macOS (Homebrew): ```bash brew tap sohilladhani/codesynapse brew install codesynapse ``` Windows (Scoop): ```powershell scoop bucket add cs https://github.com/sohilladhani/scoop-codesynapse scoop install codesynapse ``` Nix: ```bash nix run github:sohilladhani/codesynapse # run directly nix profile install github:sohilladhani/codesynapse # install permanently ``` Or add to your flake: ```nix inputs.codesynapse.url = "github:sohilladhani/codesynapse"; # then: inputs.codesynapse.packages.${system}.default ``` **Option C — Build from source** Requires Rust stable toolchain ([install](https://rustup.rs)): ```bash cargo install codesynapse-cli ``` --- ## Quick start ```bash # 1. Register the MCP server with Claude Code and/or Cursor (auto-detects both) codesynapse setup # Other clients (if not auto-detected): codesynapse opencode install # OpenCode codesynapse codex install # Codex CLI codesynapse hermes install # Hermes Agent codesynapse kiro install # Kiro # 2. Index a repository codesynapse module add myrepo /path/to/your/repo # 3. Restart your AI client # 4. Ask architecture questions — the 32 MCP tools are now available ``` That's it. From this point, queries like *"what handles auth token expiry?"* or *"show blast radius of UserService"* are answered from the graph — not from file search. **Add more repositories:** ```bash codesynapse module add backend /path/to/backend codesynapse module add frontend /path/to/frontend # Graphs are merged — cross-module queries work automatically ``` **Refresh after code changes:** ```bash codesynapse module refresh myrepo ``` **List indexed modules:** ```bash codesynapse module list ``` **Remove a module:** ```bash codesynapse module remove myrepo # Prunes its nodes from the global graph and deregisters it ``` **Keep the graph current with git (optional):** ```bash codesynapse hook install # installs a post-merge git hook — auto-refreshes on pull ``` --- ## MCP tools 32 tools across six categories, callable from Claude Code, Cursor, or any MCP-compatible client. | Category | Tools | |---|---| | **Graph search** | `codesynapse_query_vector`, `codesynapse_query_semantic`, `codesynapse_blast_radius`, `codesynapse_blast_radius_scored`, `codesynapse_blast_radius_multi`, `codesynapse_hierarchy`, `codesynapse_list_graphs`, `codesynapse_module_summary`, `codesynapse_build` | | **Code reading** | `codesynapse_resolve`, `codesynapse_outline`, `codesynapse_read`, `codesynapse_read_method`, `codesynapse_read_with_callees` | | **Navigation** | `codesynapse_find_callers`, `codesynapse_find_usages` | | **Graph analysis** | `codesynapse_query_graph`, `codesynapse_get_node`, `codesynapse_get_neighbors`, `codesynapse_get_community`, `codesynapse_god_nodes`, `codesynapse_graph_stats`, `codesynapse_shortest_path`, `codesynapse_find_all_paths`, `codesynapse_weighted_path`, `codesynapse_community_bridges`, `codesynapse_diff`, `codesynapse_pagerank`, `codesynapse_detect_cycles`, `codesynapse_smart_summary`, `codesynapse_find_similar` | | **Observability** | `codesynapse_stats` | Full parameter reference and examples: [docs/MCP-TOOLS.md](docs/MCP-TOOLS.md) **Common queries in Claude Code:** ``` "What handles auth token expiry?" → codesynapse_query_vector "Show blast radius of UserService" → codesynapse_blast_radius "What does UserRepository extend?" → codesynapse_hierarchy "Read the validate() method" → codesynapse_read_method "Who calls PaymentService.charge()?" → codesynapse_find_callers ``` --- ## Configuration Place `codesynapse.toml` in your project root. All fields are optional. ```toml # Output directory for exported graph (default: codesynapse-out/) output = "codesynapse-out" # Skip LLM extraction for doc/paper files (default: false) no_llm = false # Index source code only, skip docs and papers (default: false) code_only = false # Export formats: "json", "html", "graphml", "obsidian" formats = ["json", "html"] # LLM config for semantic extraction of docs/papers (optional) [llm] provider = "anthropic" # "anthropic" | "openai" | any OpenAI-compatible model = "claude-sonnet-4-20250514" api_key = "sk-..." # or set ANTHROPIC_API_KEY / OPENAI_API_KEY env var base_url = "https://..." # optional, for OpenAI-compatible providers # Custom model path (default: auto-resolved by codesynapse setup) [embeddings] model_path = "./models/potion-code-16M" ``` --- ## Repository layout ``` codesynapse/ ├── codesynapse-core/ # Extraction, graph, embedding, global graph ├── codesynapse-cli/ # CLI binary (module add/refresh/list, build, setup) ├── codesynapse-mcp/ # MCP server — 32 tools, JSON-RPC over stdio ├── codesynapse-serve/ # BM25 + dense hybrid search engine ├── codesynapse-tui/ # Terminal UI ├── codesynapse-grpc/ # gRPC server ├── codesynapse-graphql/ # GraphQL API ├── codesynapse-wasm/ # WebAssembly bindings ├── models/ │ └── potion-code-16M/ # Static embedding model (downloaded by setup) ├── tests/ # Integration tests └── docs/ ├── ARCHITECTURE.md └── MCP-TOOLS.md ``` Runtime data lives in `~/.codesynapse/`: ``` ~/.codesynapse/ ├── global-graph.json # Merged graph (all modules) ├── embeddings.json # node_id → Vec<f32> dense embeddings ├── modules.conf # name|/path module registry ├── global-manifest.json # Per-module hash + metadata ├── tool_stats.jsonl # MCP tool call log ├── models/potion-code-16M/ └── modules/<name>/graph.json ``` --- ## Uninstall **Remove from all AI clients:** ```bash # Re-run setup and remove the entry manually from the config files setup wrote: # Claude Code: ~/.claude.json (key: mcpServers.codesynapse) # Cursor: ~/.cursor/mcp.json (key: mcpServers.codesynapse) # Windsurf: ~/.codeium/windsurf/mcp_config.json # OpenCode: ~/.config/opencode/opencode.json ``` **Remove a specific module:** ```bash codesynapse module remove myrepo ``` **Full cleanup** (removes all indexed data): ```bash rm -rf ~/.codesynapse/ ``` --- ## Manual MCP setup If `codesynapse setup` doesn't auto-detect your client, add this entry manually: **Claude Code** (`~/.claude.json`): ```json { "mcpServers": { "codesynapse": { "type": "stdio", "command": "codesynapse", "args": ["mcp"] } } } ``` **Cursor** (`~/.cursor/mcp.json`): ```json { "mcpServers": { "codesynapse": { "type": "stdio", "command": "codesynapse", "args": ["mcp"] } } } ``` For other clients, pass the same `command`/`args` pair to their MCP server config. --- ## CLI skill (MCP-free fallback) If MCP is blocked by your org's network policy, codesynapse ships a CLI skill for Claude Code and a rules file for Cursor. Your AI client shells out to `codesynapse` directly instead of using the MCP protocol. **Claude Code** — copy into your project: ```bash mkdir -p /path/to/your/project/.claude/skills cp -r integrations/claude-code/skills/codesynapse-cli /path/to/your/project/.claude/skills/ ``` **Cursor** — copy into your project: ```bash mkdir -p /path/to/your/project/.cursor/rules cp integrations/cursor/rules/codesynapse-cli.mdc /path/to/your/project/.cursor/rules/ ``` The `integrations/` directory ships with the repository. Restart your client after copying. --- ## pi extension For [pi](https://github.com/pi-ai/pi) users, install the codesynapse extension: ```bash pi install npm:codesynapse-pi ``` This wires up 12 curated codesynapse tools and injects graph-awareness into every pi session automatically. --- ## Troubleshooting **MCP server not connecting** - Verify `codesynapse` is on your PATH: `which codesynapse` - Run `codesynapse setup` again — it re-writes the client config - Restart your AI client after setup **No results from graph queries** - Check modules are indexed: `codesynapse module list` - Rebuild the global graph: `codesynapse build` - Ensure the model downloaded: `codesynapse setup` (downloads `potion-code-16M` on first run) **Stale results after code changes** - Refresh the module: `codesynapse module refresh myrepo` - Or install the git hook for automatic refresh: `codesynapse hook install` **`codesynapse setup` says no embedding model** `codesynapse setup` downloads the model automatically. If it fails: 1. Check your internet connection and re-run `codesynapse setup` 2. Download manually from HuggingFace: ``` https://huggingface.co/minishlab/potion-code-16M/resolve/main/model.safetensors https://huggingface.co/minishlab/potion-code-16M/resolve/main/tokenizer.json https://huggingface.co/minishlab/potion-code-16M/resolve/main/config.json ``` Place all three files in `~/.codesynapse/models/potion-code-16M/`, then re-run `codesynapse setup`. **Graph query is slow** - First query after startup is slower — embeddings load from disk - Subsequent queries are fast (~1.5 ms encode + BM25 + cosine) --- ## Telemetry Telemetry is **off by default**. Enable it explicitly if you want to help improve codesynapse: ```bash codesynapse telemetry on # opt in codesynapse telemetry off # opt out + delete local queue ``` When enabled, codesynapse sends anonymous daily rollups: tool names, call counts, and coarse token-savings buckets. No query content, no file paths, no source code, no IPs. See [TELEMETRY.md](TELEMETRY.md) for the full data contract. --- ## Contributing Contributions welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. - **Bug reports:** use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) - **Feature requests:** use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) - **Code:** run `cargo test --workspace` and `cargo clippy --workspace -- -D warnings` before submitting This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md) code of conduct. --- ## License MIT — see [LICENSE](LICENSE).