codegraph

<p align="center"> <img src="docs/banner.svg" alt="codegraph" width="100%"/> </p> <p align="center"> <a href="https://github.com/isink17/codegraph/releases/latest"><img src="https://img.shields.io/github/v/release/isink17/codegraph?color=00ff88&style=flat-square&label=release" alt="Latest Release"/></a> <a href="https://pkg.go.dev/github.com/isink17/codegraph"><img src="https://img.shields.io/badge/go-1.23+-00d4ff?style=flat-square&logo=go&logoColor=white" alt="Go version"/></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-FSL--1.1--Apache--2.0-ffaa44?style=flat-square" alt="License"/></a> <img src="https://img.shields.io/badge/platforms-Linux%20%7C%20macOS%20%7C%20Windows-8899aa?style=flat-square" alt="Platforms"/> <img src="https://img.shields.io/badge/MCP%20tools-29-00ff88?style=flat-square" alt="MCP Tools"/> </p> <br/>

codegraph is a local-first code context engine and MCP server that builds a persistent knowledge graph of your source repositories in SQLite. It gives AI coding assistants deep structural awareness — symbols, call graphs, dependencies, and semantic search — without sending a single byte to the cloud.

Single binary. Zero config. No external databases. No API keys.

---

Why codegraph?

AI coding assistants are powerful, but they spend most of their token budget discovering what to change — grepping files, reading code, reconstructing call graphs from partial evidence.

codegraph shifts that cost. One call to context_for_task returns the exact files, symbols, and relationships an agent needs. One call to agentic_query gets a synthesized answer backed by graph traversal and semantic search.

❌ Without codegraph
   AI reads files one by one → greps for patterns → burns tokens on context-gathering

✅ With codegraph
   AI calls context_for_task("add retry logic to HTTP client")
   → instantly gets relevant files, functions, callers, callees, and tests

---

How It Works

Your Code ──▶ tree-sitter AST ──▶ SQLite Graph ──▶ MCP Tools ──▶ AI Assistant
                    │                   │                │
               12 languages       symbols, edges      29 tools
               framework detect   embeddings          agentic reasoning
               import resolution  session memory      hybrid search

codegraph index . walks your repo, parses every file with tree-sitter, resolves imports using four strategies (exact, name, suffix, method-receiver), and writes a fully-linked symbol graph into a local codegraph.sqlite. The MCP server then exposes that graph to any compatible AI assistant via 29 structured tools — no cloud, no Docker, no API keys.

---

Features

🔍 Parsing & Indexing

• Tree-sitter parsing for all 12 supported languages — robust AST extraction, not regex
• 4-strategy import resolution — exact, name, suffix, and method-receiver matching
• Cross-language linking — connects symbols across language boundaries
• Incremental updates — only re-indexes changed files; fast on large repos
• Framework detection — recognizes 20+ frameworks (Express, Django, gin, React, Spring, Laravel, …)

🔎 Search & Query

• Hybrid search — vector similarity (Ollama embeddings) + FTS5, fused with Reciprocal Rank Fusion
• Semantic search — find code by meaning, not just text
• Call graph traversal — callers, callees, transitive dependency chains
• Impact analysis — know what breaks before you change it
• Dead code detection — find symbols with zero references
• Architecture overview — language breakdown, entry points, hub symbols, coupling metrics

🤖 AI Integration

• 29 MCP tools — comprehensive API for AI coding assistants
• Agentic reasoning — ReAct loop over a local Ollama LLM that chains tools and synthesizes answers
• Context building — one tool call returns everything an agent needs for a task
• Session memory — persist reads, edits, decisions, and facts across sessions
• Token benchmarking — measure savings vs. naive file reading

📊 Graph Analytics

• PageRank — find the most important symbols in your codebase
• Coupling metrics — identify tightly coupled file pairs
• Cycle detection — find circular dependencies at the file level
• Interactive visualization — D3.js force-directed graph with search and zoom

🛠 Developer Experience

• Single Go binary — no runtime dependencies, cross-platform
• Zero-config SQLite — no Docker, no external databases
• codegraph install — auto-detects and configures Claude Code, Cursor, Windsurf, Gemini CLI
• File watching — automatic re-indexing on changes
• 100% local — no data leaves your machine

---

Supported Languages

All languages use tree-sitter for AST parsing:

| Language | Extensions | |---|---| | Go | .go | | Python | .py | | TypeScript | .ts, .tsx | | JavaScript | .js, .jsx, .mjs | | Java | .java | | Kotlin | .kt, .kts | | Rust | .rs | | C# | .cs | | Ruby | .rb | | Swift | .swift | | PHP | .php | | C / C++ | .c, .h, .cpp, .hpp, .cc |

Release archives use native CGO builds, so shipped binaries include the tree-sitter parsers and expose relationship-graph edges. Explicit CGO_ENABLED=0 builds use the reduced Go/Python plus heuristic parser registry and are not release-equivalent.

Node.js repos are supported; full tree-sitter node support is still in progress.

---

Quick Start

1. Install

go install github.com/isink17/codegraph/cmd/codegraph@latest

Requires Go 1.23+ and a C compiler (for tree-sitter CGo bindings).

Build from source

git clone https://github.com/isink17/codegraph
cd codegraph
go build ./cmd/codegraph
go test ./...

Requires Go 1.23+ and a C compiler (for tree-sitter CGo bindings).

Clean rebuild

cd your-project
codegraph index . --rebuild

Use this after parser or indexer changes when you need a true full reindex from scratch. codegraph index . --rebuild needs exclusive access to the repo database. If rebuild fails because the DB is in use, stop codegraph serve or other codegraph processes and retry. Use codegraph clean . for database maintenance tasks like WAL checkpointing, VACUUM, FTS optimize, ANALYZE, and incremental vacuum.

Version

codegraph --version
codegraph version

Prints the installed local version only. It does not contact GitHub.

2. Auto-configure your AI tool

codegraph install

Detects Claude Code, Cursor, Windsurf, and Gemini CLI and writes the MCP config automatically.

3. Index your project

cd your-project
codegraph index .

4. Start the MCP server

codegraph serve

Repo root is auto-detected from git (or falls back to your current working directory).

That's it. Your AI assistant now has deep structural code understanding.

---

MCP Setup

Auto-configure (recommended)

codegraph install

Manual Setup

<details> <summary><strong>Claude Code</strong> — add to <code>.mcp.json</code></summary>

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["serve"]
    }
  }
}

</details> <details> <summary><strong>Cursor / Windsurf</strong> — add to <code>mcp.json</code></summary>

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["serve"]
    }
  }
}

</details> <details> <summary><strong>Codex</strong> — add to <code>config.toml</code></summary>

[mcp_servers.codegraph]
command = "codegraph"
args = ["serve"]
startup_timeout_sec = 60

</details>

See the examples/ directory for more configuration samples.

---

Agent Skill

skills/codegraph is an Agent Skills–compatible skill that teaches coding agents the efficient CodeGraph workflow: narrow graph context first, targeted drill-down, caller/callee and impact reasoning, source verification. Install it with the skills CLI:

npx skills add isink17/codegraph --skill codegraph                       # pick agents interactively
npx skills add isink17/codegraph --skill codegraph -a claude-code -a codex
npx skills add isink17/codegraph --skill codegraph -g                    # global instead of per-project

It works with any client that supports Agent Skills; the skill itself covers both MCP modes (full and gateway) and the CLI fallback.

---

MCP Tools (29)

Code Intelligence

| Tool | Description | |---|---| | find_symbol | Find symbols by exact or fuzzy query | | search_symbols | Search symbol names, signatures, and docs (FTS5) | | search_semantic | Hybrid semantic search (vector + FTS when embeddings enabled) | | find_callers | Find what calls a given function | | find_callees | Find what a given function calls | | get_impact_radius | Estimate affected symbols and files around a change | | trace_dependencies | Trace transitive dependency chains (upstream/downstream) | | find_related_tests | Find tests for a symbol, file, or set of changed files | | find_dead_code | Find symbols with no callers or references | | context_for_task | Build a focused, token-budgeted context bundle for a natural-language task |

Architecture & Analysis

| Tool | Description | |---|---| | architecture_overview | Language breakdown, directories, entry points, hub symbols | | graph_analytics | PageRank, coupling metrics, or cycle detection | | detect_frameworks | Detect frameworks and libraries used in the repo | | cross_language_links | Find and create cross-language symbol references | | benchmark_tokens | Estimate token savings vs. reading raw files |

Repository Management

| Tool | Description | |---|---| | index_repo | Index a repository into the local code graph | | update_graph | Update only changed files | | list_files | List indexed files with optional path filter | | graph_stats | Repository graph statistics | | supported_languages | List supported languages and extensions | | list_repos | List known repositories | | list_scans | List recent scans | | latest_scan_errors | List indexer errors from the last scan | | audit | Audit the indexed graph for integrity, resolver-correctness, and trust issues (read-only). Optional examples integer caps examples per finding; 0 means counts only |

Session Memory

| Tool | Description | |---|---| | session_log | Log a session event (read, edit, decision, task, fact) | | session_history | Get session event history | | session_hot_files | Get most frequently accessed files | | session_context | Get aggregated session context for pre-loading |

Agentic

| Tool | Description | |---|---| | agentic_query | Ask a question answered by a local AI agent that reasons over the code graph (requires Ollama) |

Progressive disclosure (detail)

find_symbol, search_symbols, find_callers, find_callees, and get_impact_radius accept an optional detail argument. It controls how much of each symbol comes back, and nothing else -- traversal results still report the same symbols, files, and counts at every level.

| detail | What each symbol carries | Use it to | |---|---|---| | card (default) | name, qualified name, kind, language, file, line, symbol id, stable key | choose between candidates and drill down | | skeleton | + signature, visibility, container, doc summary, end line, member declarations | inspect an API or a type's shape | | excerpt | + source around the symbol: a few lines of context, capped tightly, marked truncated when the symbol is longer | read the implementation around a target | | full | + the same window with a far higher cap, so it always contains what excerpt returned, plus range and file_id | take everything, explicitly |

detail=full returns every field these tools re