GraphCode

GraphCode is a structural preflight tool for codebases.

It helps answer three questions:

1. If I change this, what else is affected?
2. Does this flow still have a structural path?
3. If it breaks, which side should I inspect first?

GraphCode is best used before deep code reading or editing. It narrows the search space, then hands off to tools like Serena for code truth and refactoring.

What It Does

• builds a deterministic graph from a local repository
• produces structural artifacts such as impact graphs and corridor graphs
• helps with impact analysis, cross-system tracing, and inspect-first reasoning
• runs as both a CLI and a local stdio MCP server

What It Is Not

• not a replacement for Serena
• not runtime truth
• not a general semantic coding agent

When To Use It

Use GraphCode when:

• the repo is large or unfamiliar
• you need blast-radius analysis before changing code
• you want to trace a cross-module or cross-repo flow
• you want a structural answer for where to inspect first

Do not start with GraphCode when:

• you already know the exact file and symbol to edit
• the task is a local bug fix inside one file
• you mainly need code reading or refactoring rather than structural mapping

Install

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/iylmwysst/GraphCode/master/install.sh | sh

The installer:

• creates a virtualenv under ~/.local/share/graphcode/venv
• installs GraphCode from GitHub
• links graphcode, graphcode-mcp, and graphcode-mcp-smoke into ~/.local/bin

If ~/.local/bin is not already on your PATH, add:

export PATH="$HOME/.local/bin:$PATH"

Use With Codex

Register GraphCode as a local stdio MCP server:

codex mcp add graphcode -- graphcode-mcp

Check that Codex can see it:

codex mcp get graphcode

If you prefer manual config:

[mcp_servers.graphcode]
command = "graphcode-mcp"

CLI Quick Start

Build the default repo-local graph artifact:

graphcode init /path/to/repo

Run a front-door structural query:

graphcode query --repo-path /path/to/repo --tool macro_graph

The default graph is stored at:

/path/to/repo/.graphcode/graph.json

If the graph file is missing, graphcode query will auto-build it.

Recommended Workflow

For a large or unfamiliar codebase:

graphcode init /path/to/repo
graphcode query --repo-path /path/to/repo --tool macro_graph
graphcode query --repo-path /path/to/repo --tool list_groups
graphcode query --repo-path /path/to/repo --tool focus_group --orbit ui

For impact analysis:

graphcode query --repo-path /path/to/repo --tool impact_report --node-id function:src/app.py:main

For cross-system tracing:

graphcode query --repo-path /path/to/repo --tool macro_corridor --source-group ui --target-group api
graphcode query --repo-path /path/to/repo --tool flow_verdict --source-node-id function:src/app.py:main --target-node-id function:src/service.py:handle
graphcode query --repo-path /path/to/repo --tool boundary_report --source-node-id function:src/app.py:main --target-node-id function:src/service.py:handle
graphcode query --repo-path /path/to/repo --tool corridor_graph --source-node-id function:src/app.py:main --target-node-id function:src/service.py:handle

Mental Model

GraphCode works best as a hierarchy:

• macro_graph: large project or workspace structure
• focus_group and child_graph: one subsystem or group
• macro_corridor and corridor_graph: one flow between source and target
• impact_report and impact_graph: one seed and its blast radius

Start broad, narrow to the right group, then materialize the corridor or impact artifact you need.

Current Scope

GraphCode currently supports:

• Python source analysis via ast
• mixed Rust and TypeScript workspaces via a heuristic extractor
• deterministic graph building and query artifacts
• local stdio MCP usage for coding agents

Docs

• Concept
• Roadmap
• Differentiation
• Project Status

Historical and superseded material lives under docs/archive.

License

MIT. See LICENSE.