Compiler-aware repository context for Go coding agents

gograph builds a local structural graph of a Go repository, with optional type-checked CHA/SSA enrichment. Use it to trace callers and interface implementations, plan change impact, and enforce architecture through CLI or MCP without embeddings or a hosted code index.

gograph build .           # fast AST graph; tolerates incomplete packages
gograph stats             # verify build health and analysis precision
gograph summary           # repository overview; no symbol name required
gograph hotspot --top 5   # choose a real symbol for context or plan
gograph flow --no-tests   # potential production source-to-sink paths

For a compilable repository, run gograph build . --precise before a major refactor. Then pass a real function or method reported by hotspot, summary, or complexity to gograph context and gograph plan.

Real Command Output Example

This captured example shows the output shape for callers of loadGraph; symbols and line numbers evolve with the repository:

$ gograph callers loadGraph

[caller] BuildBaselineGraphFromGitRef — calls loadGraph  ->  `return buildGraph(tmpDir)`  (internal/cli/baseline.go) [call @ internal/cli/baseline.go:84]
[caller] NewServer$14 — calls loadGraph  ->  `baselineGraph, err := buildGraph(tmpDir)`  (internal/mcp/server.go) [call @ internal/mcp/server.go:531]
[caller] runAPI — calls loadGraph  ->  `currentGraph, err := loadGraph(".")`  (internal/cli/api.go:11) [call @ internal/cli/api.go:29]
[caller] runArity — calls loadGraph  ->  `g, err := loadGraph(".")`  (internal/cli/cli.go:1341) [call @ internal/cli/cli.go:1352]
[caller] runErrorFlow — calls loadGraph  ->  `g, err := loadGraph(".")`  (internal/cli/cli.go:2046) [call @ internal/cli/cli.go:2064]
[caller] runPlan — calls loadGraph  ->  `g, err := loadGraph(".")`  (internal/cli/cli.go:2433) [call @ internal/cli/cli.go:2450]
[caller] runStats — calls loadGraph  ->  `g, err := loadGraph(".")`  (internal/cli/cli.go:1241) [call @ internal/cli/cli.go:1242]

Designed for focused agent workflows

Text search remains useful for strings, documentation, configuration, and non-Go files. Language servers provide live compiler-backed navigation and refactoring. gograph adds persisted repository structure and composed change-analysis responses for coding agents such as Claude Code, Cursor, Copilot, Antigravity, and OpenCode.

Focused structural evidence: AST-derived results avoid comments and raw string matches when the question is about Go symbols or relationships.
Explicit correctness modes: Build metadata distinguishes AST-only, successful precise analysis, and visible precise fallback.
Composed workflows: context, plan, review, and summary combine related graph evidence. Savings depend on the repository and task.

Install

Homebrew

brew install ozgurcd/tap/gograph

Go install

go install github.com/ozgurcd/gograph/cmd/gograph@latest

Official MCP Registry / MCPB (preview)

io.github.ozgurcd/gograph

This installs a platform-specific local MCP bundle in clients that support MCPB; it does not place the CLI on PATH. Select the Go project directory and the macOS/Linux/Windows amd64/arm64 asset matching the host. See the Registry guide for the current CPU-selection limitation.

From source

git clone https://github.com/ozgurcd/gograph
cd gograph
make build
sudo make install

How it works

gograph build . — walks Go files selected by the shared scanner, extracts symbols, validated call edges, imports, HTTP routes, SQL queries, environment reads, struct fields, error declarations, and typed synchronization primitives. Writes everything under the target .gograph/ directory, adds .gograph/ to the enclosing Git repository root .gitignore when available, and falls back to the build target .gitignore outside Git. A zero-file or zero-successful-parse build does not replace existing artifacts; partial failures are recorded in atomically published graph metadata.
CLI query commands — read persisted graph.json; rebuild after source changes. MCP source-analysis tools check source freshness and newer persisted artifacts, adopt a newer precise graph, and rebuild after edits in the current requested mode. A failed precise refresh is returned visibly.
--precise mode — attempts type-checked CHA/SSA enrichment. It needs compilable, build-selected packages for precise data; if type/load analysis fails or omits an indexed non-test file, gograph warns, retains the AST graph, and records precise_fallback (precise and ast identify the other modes).

What it captures

Signal	How extracted
Functions, methods, structs, interfaces, types, consts	AST `FuncDecl`, `TypeSpec`
Call edges (caller → callee, with call-site file and line)	AST `CallExpr`
HTTP routes (method + path + handler)	`gin`, `echo`, `chi`, `http.Handle*` literal patterns
SQL queries	String literal heuristics on `db.Query`, `db.Exec`, etc.
Environment reads	`os.Getenv`, `viper.Get*`
Struct field mutations	AST `AssignStmt` on selector expressions
Error declarations and return sites	`errors.New`, `fmt.Errorf`, `panic`
Concurrency primitives	`go func`, `sync.Mutex`, channel ops, `WaitGroup`
Test edges (test → tested symbol)	`_test.go` call analysis
Composite literal sites	`StructName{...}`
Security flow facts	Sources, assignments, calls, returns, and sensitive sinks for query-time analysis

Why use it?

Use rg for text and non-Go searches and gopls for live compiler-backed navigation, diagnostics, implementations, and refactoring. gograph complements them with persisted repository-level questions such as:

What is the blast radius of changing this function?
What interfaces does this struct satisfy?
What errors can this HTTP handler return, and where do they originate?
Which symbols changed since my last commit and what tests cover them?
Is this function reachable from any entry point, or is it dead code?
Can HTTP, decoded JSON, or environment data reach a security-sensitive sink?

These questions require a full in-memory call graph. gograph builds that graph and lets you query it directly from the terminal or from an AI agent via MCP.

gograph

A local structural graph for safer Go refactors, repository-level analysis, and coding-agent workflows — from the terminal or any compatible MCP client.

Getting Started

Prerequisites Go 1.26 or later A Go module repository (go.mod present) Install Homebrew (recommended) brew install ozgurcd/tap/gograph gograph version Go install go install github.com/ozgurcd/gograph/cmd/gograph@latest gograph version Official MCP Registry / MCPB (preview) MCPB-capable clients can discover io.github.ozgurcd/gograph in the official Registry. This installs a self-contained local MCP server bundle rather than a CLI on PATH. Select the bundle matching macOS, Linux, or Windows and the host’s amd64/arm64 architecture, then choose the root directory of the Go project to analyze. Current Registry metadata cannot select CPU architecture portably, so verify the asset filename instead of assuming automatic client selection. See Official MCP Registry for details. ...

Command Reference

This reference documents every command available in the gograph CLI, compiled directly from the production source code. Indexing & Core Commands build gograph build [path] [--precise] Walks and parses a Go repository. Generates the structured graph at .gograph/graph.json and nine targeted Markdown reports in .gograph/. Adds .gograph/ to the Git repository root .gitignore when available; outside Git, falls back to the build target .gitignore. Git-ignored files and directories use the same exclusion policy in build, stale, and changes. If no Go files are found or none parse successfully, exits without replacing existing artifacts. Partial parse failures are recorded in graph.json, which is committed with an atomic rename. ...

AI Agent Integration

gograph is an agent-oriented static-analysis tool. Humans can use the CLI, while MCP clients such as Claude Code, Cursor, Copilot, Antigravity, and OpenCode can request the same structured repository evidence. Results follow the documented AST, precise-analysis, and heuristic limits; they are not runtime proof. Text search, gopls, and gograph have different jobs rg, grep, and find are appropriate for literal text, documentation, configuration, generated content, and non-Go files. Text matching alone cannot resolve Go interface satisfaction or distinguish a call expression from a comment or string. ...

Agent Workflows

To maximize efficiency, reduce latency, and guarantee safety when modifying codebases, we recommend following these standardized workflows. These steps can be programmed into AI system instructions or executed manually. Workflow 1: Onboarding to a New Repo When opening an unfamiliar Go repository, use this workflow to get oriented in seconds: Verify Index Status: gograph stats gograph stale If stale or missing, run gograph build .. Find High-Risk Hotspots: gograph hotspot --top 10 Identifies the most heavily referenced functions in the codebase. Map Package Coupling: gograph coupling Gives a high-level table showing package stability and dependencies. Inspect the Global API Surface: gograph skeleton Exposes every package signature with bodies stripped. Workflow 2: Safe-Edit Symbol Lifecycle Before changing the signature or behavior of any function, method, or struct, follow this cycle: ...

Official MCP Registry

gograph is published to the official Model Context Protocol Registry as: io.github.ozgurcd/gograph The official Registry is currently in preview. Its API, stored data, and client support may change before general availability. Registry installation is a separate path Homebrew and go install place the normal gograph CLI on PATH. You then configure an MCP client to run gograph mcp <project-directory>. The Claude Code marketplace entry supplies workflow guidance but still needs that binary and a project registration. ...

Compiler-aware repository context for Go coding agents#

Real Command Output Example#

Designed for focused agent workflows#

Install#

How it works#

What it captures#

Why use it?#