简体中文

CodeGraph

A code knowledge graph plugin: parses a codebase into a queryable index, so agents can answer structural questions like "who calls this function" or "what does this module depend on". Good for quickly understanding large codebases, or as a risk-screening tool before making changes.

Self-contained implementation: Python standard library + SQLite, no mandatory third-party dependencies. Ships a CLI, a Python API, and a stdio tool server (MCP-style JSON-RPC 2.0) that any plugin-based harness can load as a subprocess.

Features

• Call graph: callers / callees — who calls a given function/method, and what it calls
• Dependency graph: deps / dependents — what a module or file imports and who imports it (internal resolution vs. external dependencies)
• Full-text search: search — local full-text search over symbol names, docstrings and signatures (SQLite FTS5, no external service)
• Impact analysis: impact — transitive closure listing "who would be affected if this symbol changed"
• Incremental indexing: content-hash comparison re-parses only changed files; deleted files are cleaned up automatically
• Visualization export: export dot|json — Graphviz DOT / JSON, ready to drop into visualization tools
• Query cache: the tool server caches read-only queries with a 30-second TTL
• Two parse engines: tree-sitter (precise, optional install) and a regex scanner (zero-dependency fallback), chosen automatically

How it works

file discovery (include/exclude/size limit)
   → syntax extraction (symbols, call sites, import statements)
   → SQLite storage (files / symbols / calls / imports + FTS5)
   → cross-file resolution (call targets → symbols, imports → files)
   → queries (CLI / tool server / Python API)

Cross-file resolution is heuristic and tries, in priority order: exact match in the same file → files reachable by import → same package/module family → globally unique name. Call sites that fail to resolve keep their raw text and are marked unresolved (external code, standard library, third-party packages).

Installation

# Option A: install as a Python package (provides the codegraph command)
pip install -e .

# Optional: install tree-sitter grammar packages for markedly better parse precision
pip install -e ".[treesitter]"

# Option B: use directly from the repo without installing
set PYTHONPATH=src        # Windows
export PYTHONPATH=src     # Linux/macOS
python -m codegraph --help

Requires Python ≥ 3.10. Supported languages: Python, JavaScript, TypeScript, Go, Java, Rust.

Quick start

cd examples/demo

# 1. Build the index (incremental; refresh at any time)
codegraph index
# indexed 4 files (4 changed, 0 skipped, 0 removed) ... 6 symbols, 7 calls, 3 imports

# 2. Ask questions
codegraph callers services.orders.create_order     # who calls create_order → app.run
codegraph callees app.run                          # what app.run calls
codegraph deps services.billing                    # what the billing module depends on
codegraph dependents services.billing              # who depends on billing
codegraph search "coupon"                          # full-text search
codegraph impact services.billing.price            # impact (transitive callers)
codegraph status                                   # index statistics
codegraph export dot -o graph.dot                  # export a visualization

Command line

…