CodeGraphContext

Python MCP server and CLI toolkit that indexes codebases into a graph database using Tree-sitter parsing. Enables relationship-aware code queries (callers, d…

CodeGraphContext

Python MCP server and CLI toolkit that indexes codebases into a graph database using Tree-sitter parsing. Enables relationship-aware code queries (callers, dependencies, blast radius, dead code) without reading every file.

GitHub: CodeGraphContext/CodeGraphContext — v0.4.9, ~3.2k stars.

---

Architecture

Source files
    ↓  Tree-sitter parsing (20 languages)
Abstract Syntax Trees
    ↓  entity/relationship extraction
Graph DB (KuzuDB default)
    ↓  MCP server
Claude Code tools

Parsing: Tree-sitter — fast, grammar-based, language-specific. No compiler required for most languages.

Graph DB options:

• KuzuDB (default) — embedded, all platforms, no setup
• FalkorDB Lite — Unix only; faster for large repos
• Neo4j — enterprise/Docker; persistent across machine restarts

SCIP optional: C/C++ needs compile_commands.json (generated by cmake/bear). C# needs .csproj. All other languages work without it.

---

Supported Languages (20)

Python, JavaScript, TypeScript, TSX, Java, C, C++, C#, Go, Rust, Ruby, PHP, Swift, Kotlin, Dart, Perl, Lua, Scala, Haskell, Elixir.

---

Install + Setup

pip install codegraphcontext

# Index current directory
codegraphcontext index .

# Index + watch simultaneously (daemon mode — live updates)
codegraphcontext watch .

# Auto-configure Claude Code (writes .claude.json)
codegraphcontext mcp setup

# Start MCP server
codegraphcontext mcp start

.cgcignore (gitignore syntax) controls exclusions — place at repo root.

---

MCP Tools

Tool	Purpose
find_code	Symbol/function/class lookup by name
find_dead_code	Unused exports, unreachable definitions
analyze_code_relationships	Callers, dependencies, blast radius
find_most_complex_functions	Cyclomatic complexity ranking
calculate_cyclomatic_complexity	Complexity score for a specific function
get_repository_stats	File count, language breakdown, graph stats
list_indexed_repositories	Check what’s already indexed (idempotency check)
add_code_to_graph	Incremental add without full re-index
add_package_to_graph	Index a package/module specifically
delete_repository	Remove index
watch_directory	Start daemon for live updates
unwatch_directory	Stop daemon
list_watched_paths	Active watch jobs
check_job_status	Async job progress
list_jobs	All running/completed jobs
execute_cypher_query	Raw graph query (KuzuDB Cypher syntax)
visualize_graph_query	Graph visualization output
search_registry_bundles	Search pre-built index bundles
load_bundle	Load a pre-built bundle (skip indexing)

---

Query Routing Table

Use this to decide between grep, CGC, and qmd:

Query type	Best tool
”Where is function X defined?“	grep / ripgrep
”What calls X?”	CGC: analyze_code_relationships
”What does X depend on?”	CGC: analyze_code_relationships
”Blast radius of changing X”	CGC: analyze_code_relationships
”Dead code / unused exports”	CGC: find_dead_code
”Most complex functions”	CGC: find_most_complex_functions
”Overall codebase structure”	CGC: get_repository_stats
”Design pattern for X”	qmd wiki
”How does wiki concept apply?“	qmd first → CGC to ground in code

Grep only finds definitions. CGC finds relationships. Never substitute grep for relationship queries.

---

When to Index (Decision Threshold)

Index with CGC if ANY of:

• 2+ distinct source languages in the repo

• 100 source files

• Infra files present (Dockerfile, docker-compose, CI YAML, Terraform, k8s)

Triggered automatically by the claude-init skill Step 0.5.

---

Persistence Model

Mode	How	When
Session	codegraphcontext index . at session start	Unfamiliar codebases; one-time exploration
Daemon	codegraphcontext watch . (background)	Daily-driver projects; keeps graph current as files change

Flag-first state machine

CGC status is recorded in .claude/profile.md. Claude always checks this flag first — before running any bash commands or asking any questions:

grep "^codegraphcontext:" .claude/profile.md 2>/dev/null

Flag value	Meaning	Behavior
codegraphcontext: enabled	Daemon active	Verify index live; re-index silently if missing
codegraphcontext: session	Indexed, no daemon	Ask “re-index?” at session start
codegraphcontext: disabled	User declined	Hard skip — never ask again
(missing)	Not yet evaluated	Run analysis + ask “Add CGC?”

disabled is a permanent no. To override: user must explicitly say “check CGC for this repo”.

---

Relation to Existing Wiki

• Agent Harness — CGC is a knowledge tool that improves harness quality by reducing blind grep loops
• Local Wiki RAG: LightRAG Graph Stack — complementary to qmd (wiki/docs) and LightRAG (concept graph); CGC covers code graph
• Context Degradation Patterns — CGC reduces context distraction by returning precise relationship facts instead of raw file dumps
• Tool Design for Agents — list_indexed_repositories as idempotency gate follows agent-tool design principles