Quick Start

Requires Zig 0.16.0 or later.

git clone https://github.com/dajneem23/z-codebase-mcp.git
cd z-codebase-mcp

# Debug build
zig build                          # → zig-out/bin/cbm (~10 MB)

# Release build (recommended)
zig build -Doptimize=ReleaseFast   # → zig-out/bin/cbm (~2.2 MB)

MCP Server

Add to your agent's MCP configuration:

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/zig-out/bin/cbm"
    }
  }
}

For Claude Code, add to .mcp.json in your project root or ~/.claude/claude_desktop_config.json.

CLI Mode

All 14 tools can be invoked directly from the command line:

# Index a repository
cbm cli index_repository '{"repo_path":"/path/to/repo"}'

# Search by name or keyword
cbm cli search_graph '{"project":"myproject","query":"handleRequest"}'

# Trace call chains
cbm cli trace_path '{"project":"myproject","function_name":"main","mode":"calls"}'

# Architecture overview
cbm cli get_architecture '{"project":"myproject"}'

# Cypher queries
cbm cli query_graph '{"project":"myproject","query":"MATCH (n:Function)-[r:CALLS]->(m) RETURN n.name, m.name LIMIT 10"}'

# Git change impact analysis
cbm cli detect_changes '{"project":"myproject","depth":20}'

# Architecture Decision Records
cbm cli manage_adr '{"project":"myproject","mode":"update","title":"Use SQLite for storage","content":"..."}'

All 14 MCP Tools

Indexing

Search & Query

Analysis

Metadata

Graph Data Model

Node Labels

Project, Package, Folder, File, Module, Class, Function, Method, Interface, Enum, Type, Route, Variable

Edge Types

Cypher Query Examples

Run these via query_graph:

-- All HTTP calls between services
MATCH (a)-[r:HTTP_CALLS]->(b)
RETURN a.name, b.name, r.url_path, r.method
LIMIT 20

-- Functions with "Handler" in their name
MATCH (f:Function)
WHERE f.name =~ '.*Handler.*'
RETURN f.name, f.file_path, f.start_line

-- What does main() call (up to 3 hops)?
MATCH (n:Function {name: 'main'})-[r:CALLS*1..3]->(m)
RETURN n.name, m.name, length(r) AS hops

-- Most-called functions (high fan-in)
MATCH (a)-[r:CALLS]->(b:Function)
RETURN b.name, count(r) AS callers
ORDER BY callers DESC
LIMIT 20

-- Dead code: functions with no callers and no call targets
MATCH (f:Function)
WHERE NOT (()-[:CALLS]->(f)) AND NOT (f)-[:CALLS]->()
RETURN f.name, f.file_path

Language Support

Tree-sitter Grammars (compiled, loaded at runtime)

Grammar .dylib files are compiled from source via tree-sitter generate and loaded at runtime via dlopen. To compile grammars:

cd grammars
for lang in go python rust zig c cpp javascript typescript tsx; do
  git clone --depth 1 "https://github.com/tree-sitter/tree-sitter-${lang}" "$lang" 2>/dev/null || true
  (cd "$lang" && tree-sitter generate 2>/dev/null && cp *.dylib "../${lang}.dylib") &
done
wait

Regex Fallback (always available)

For languages without compiled grammars, the regex-based fallback_extractor provides broad coverage:

The regex fallback detects functions, methods, classes, interfaces, enums, and intra-file call edges. It pre-filters lines with isInterestingLine() (skips blanks, comments, imports) for speed.

Performance

Standalone Benchmarks (M1 MacBook Pro, ReleaseFast)

Zig vs C — Head-to-Head (22 repos, ReleaseFast)

Zig Wins (16 of 22 repos)

C Wins (5 of 22 repos — all JS/TS-heavy)

🎉 Tree-sitter JS grammar added! React: 81s → 23