codegraph

简体中文

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, without installing from the repo (run from the repository root):

Windows Command Prompt:

set "PYTHONPATH=%CD%\src"
python -m codegraph --help

Windows PowerShell:

$env:PYTHONPATH = Join-Path (Get-Location) "src"
python -m codegraph --help

Linux/macOS:

export PYTHONPATH="$(pwd)/src"
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)
python -m codegraph index
# indexed 4 files (4 changed, 0 skipped, 0 removed) ... 6 symbols, 7 calls, 3 imports

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

Command line

Common options (before or after the subcommand): --root project root, --config config file, --db override database path, --json machine-readable output.

Tool interface (harness integration)

codegraph serve starts a stdio tool server: reads newline-delimited JSON-RPC 2.0 messages from stdin, writes responses to stdout, and sends all logs to stderr. It implements the handshake subset MCP needs (initialize, tools/list, tools/call, ping) and works with any MCP client or harness that speaks JSON-RPC directly.

8 tools (full JSON Schemas are in plugin.json):

All tools except reindex are read-only and share a 30-second TTL query cache. When no index exists, read-only tools return an error with isError: true.

Minimal conversation example:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"any-harness","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"callers","arguments":{"symbol":"pkg.pricing.price"}}}

Installing in DSH

dsh (DeepSeek Harness, a plugin-based agent harness) loads this plugin through its built-in MCP client, with a single line of configuration:

dsh plugin --profile demo add github:JohnXu22786/codegraph

Remove with:

dsh plugin --profile demo remove dsh-codegraph

See docs/dsh-integration.md for the full integration guide.

The repo also ships a self-contained Node bridge (index.js + dsh.bundle + cordis.patch.yml): once installed, the eight codegraph tools are registered directly as codegraph_callers / codegraph_callees / codegraph_deps / codegraph_dependents / codegraph_search / codegraph_impact / codegraph_overview / codegraph_reindex. The bridge keeps one Python stdio server alive per configured root and sends JSON requests to it (default root: the harness working directory; override per call with the root argument). Requests for the same root are serialized, and each request supports a timeout and cancellation. If the server cannot start, the bridge falls back to the one-shot Python CLI. No index yet? Call codegraph_reindex first — read-only tools return a readable error until then.

When another harness launches plugin.json's Python entry directly, install CodeGraph as a Python package or set PYTHONPATH to this plugin's src directory. The DSH Node bridge sets that path automatically.

Configuration

codegraph.json (at the project root, generated by codegraph init; key fields shown below — exclude has 17 defaults, abbreviated here):

{
  "root": ".",
  "include": [],
  "exclude": [".git", "node_modules", "dist", "build", "venv", "target", ".cg"],
  "max_file_kb": 512,
  "incremental": true,
  "engine": "auto",
  "language_map": {}
}

• include: when non-empty, only matching path prefixes/globs are indexed
• exclude: directory names or glob patterns pruned during the walk
• max_file_kb: files larger than this are skipped (usually big/generated files)
• engine: auto (tree-sitter when grammar packages exist, otherwise regex) / quick / deep
• language_map: custom extension mapping, e.g. {".md": "markdown"} reserved
• The database lives at <root>/.cg/cg.sqlite by default (that directory is excluded by default, so the index never includes itself)

Environment variable overrides: CODEGRAPH_ROOT, CODEGRAPH_DB, CODEGRAPH_MAX_FILE_KB, CODEGRAPH_ENGINE.

Incremental indexing

On by default. Every index run computes a SHA-256 of each file's content and compares it with what the database recorded: unchanged files are skipped (second-level refreshes), changed files have all their lines atomically replaced (delete + insert within a single transaction), and deleted files are removed from the store. --force or reindex force=true forces a full re-parse.

Exporting visualizations

codegraph export dot -o graph.dot     # Graphviz format: symbols as nodes, calls as solid edges, unresolved calls as dashed edges, module imports as dotted file-to-file edges
codegraph export json -o graph.json   # structured data: files/symbols/calls/imports/meta

Known limitations

• The regex engine (engine: quick) is not string/comment aware: foo( inside a string can be recorded as a call site; signatures are single-line only
• The tree-sitter engine (engine: deep) does not yet extract symbols for a few node shapes like arrow-function constants or object methods
• Cross-file call resolution is heuristic: same-name methods stay unresolved when not globally unique; dynamic calls (reflection, getattr, dynamic import) cannot be resolved
• Macro invocations (e.g. println!) are not recorded as call sites
• These only affect precision in edge cases, never the core query path; index quality improves by installing tree-sitter grammar packages

Directory structure

├── pyproject.toml            # packaging and dependency declarations
├── plugin.json               # plugin manifest: entry, tool schemas, config schema
├── README.md
├── docs/
│   └── dsh-integration.md    # harness integration guide
├── examples/demo/            # a demo project you can try immediately
├── src/codegraph/
│   ├── cli.py                # command-line entry
│   ├── config.py             # config loading (file + environment variables)
│   ├── models.py             # data models (symbols/calls/imports)
│   ├── store.py              # SQLite storage layer + FTS5
│   ├── builder.py            # index building (incremental)
│   ├── resolver.py           # cross-file resolution
│   ├── queries.py            # query API
│   ├── exporter.py           # DOT/JSON export
│   ├── cache.py              # TTL query cache
│   ├── scanner/              # file discovery + two parse engines
│   │   ├── walk.py           #   discovery and ignore rules
│   │   ├── quick.py          #   regex engine (zero-dependency)
│   │   └── deep.py           #   tree-sitter engine (optional)
│   └── server/               # stdio tool server
│       ├── handlers.py       #   tool definitions/execution/rendering
│       └── mcp.py            #   JSON-RPC protocol layer
└── tests/                    # 130 unit/integration tests (+ node:test bridge cases)

Tests

python -m unittest discover -s tests -t .

License

MIT — see LICENSE.