gograph is a locally running Go static analysis engine with a built-in MCP server, designed to provide AI coding agents with deterministic code structure awareness. By building a structural graph of the repository, it helps agents understand struct embedding, public API surfaces, SQL queries, and error mappings in Go codebases without relying on grep.
Main Capabilities
- Symbol Query: Supports path/to/file.go:Name, path/to/file.go:Receiver.Method, or import-qualified file paths, can query struct fields, and --no-tests excludes test file lines.
- Call Graph and Impact Analysis: Traces callers and interface implementations, plans change impact, and supports precise/possible impact analysis.
- Change Assessment: review --uncommitted includes deleted declarations, but explicitly does not assess historical callers, tests, and risks.
- Architecture Constraints: Enforces architecture rules through policy commands.
- Precise Indexing: Optional type-checked CHA/SSA enhancement, including package-level constant references (comparisons, switch cases, composite values, function arguments), preserving the declaration identity of typed enum constants and excluding local shadowing.
- Graph State and Freshness: Outputs freshness_context, the CLI uses the Go context of the querying process (including GOFLAGS), and MCP uses the startup context and explicit tags. A context mismatch is considered stale even if the source bytes are unchanged.
- Machine-Readable Validation: Supports four predicates: symbol_exists, package_imports, call_edge_exists, and type_implements. Read-only validation, with exit code 0 for pass, 1 for fail, 2 for unable to evaluate or invalid request.
- MCP Server: Registers 68 endpoints (including four session lifecycle tools), providing project-level query, analysis, and workflow capabilities for MCP clients such as Claude, Cursor, and Copilot.
- Federated Workspace: Models multiple checked-out repositories through independently fingerprinted repository graphs and deterministic cross-repository overlays, supporting resolution of Go modules, cross-repository Go calls, and HTTP contracts.
Usage
- Installation: Install the regular gograph CLI via Homebrew or go install.Clients that support MCP Bundles can discover the local stdio server (io.github.ozgurcd/gograph) from the official MCP Registry.
- CLI Commands: Includes summary, hotspot, complexity, query, source, tests, review, changes, plan, flow, validation, policy, and more.
- MCP Integration: CLI commands map to MCP's gograph_<command>, and the workspace server provides status, query, path, and impact.
- Build Artifacts: Written to the target .gograph/ directory, and .gograph/ is automatically added to .gitignore.
- Memory Mode: --memory-mode=low together with --max-memory can reduce memory usage, but may increase CPU time.
- Precise Fallback: Default exit code is 0, and --strict together with --precise can make fallback fail CI.
Applicable Scenarios
- AI-assisted refactoring and change impact analysis for Go codebases.
- Architecture constraint enforcement and code structure validation.
- Cross-repository call and contract analysis for multi-repository workspaces.
- Providing deterministic structural context for coding agents, reducing reliance on grep.
Limitations
- Only supports the Go language, and does not prove runtime behavior or business correctness.
- CHA edges are possible static targets, not runtime dispatch determinism.
- V1 validation excludes reachability, unstable or external symbol identity, unnamed types, and non-Go languages.
- Precise builds may be blocked by irrelevant directories, requiring the use of --exclude-dirs.
- Persistent graphs are bound to a valid Go environment and build choices, and context mismatches are considered stale.
- Old binaries do not enforce boundaries, and untrusted repositories should not be analyzed.
- Session telemetry is stored locally in .gograph/sessions/ and is not sent to the gograph service.
