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.

Try verified gograph output without installing →

Inspect the precise interface and change-context benchmark, its declared ground truth, exact commands, and complete raw output. Read the methodology and limitations →

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. A failed precise retry does not replace an existing fresh precise artifact covering the same selected sources.
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)

Registry server ID: io.github.ozgurcd/gograph (this is an identifier, not a web address). View installation details or inspect the official Registry records.

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 . — first rejects linked/non-regular go.mod, go.sum, go.work, go.work.sum, and vendor/modules.txt metadata before toolchain use. Applicable go.work use members must remain beneath the workspace directory, and their directories, go.mod, and optional go.sum are validated before cmd/go. The shared scanner then excludes linked/special recognized Go build inputs before build selection and AST reads. It extracts symbols, validated call edges, imports, HTTP routes (including constant nested Gin/Echo/Fiber groups and Chi Route closures), SQL queries, environment reads, struct fields, error declarations, and typed synchronization primitives. Each parsed file stores a SHA-256 digest; later builds reparse changed packages and reuse parser records for unchanged packages. Graph/report publishers require a real .gograph directory and regular-or-absent lock entry, stage graph.json plus nine reports, rename the reports first, and rename graph.json last as the commit marker. Same-directory replacement is atomic on Unix-like systems but is not guaranteed atomic by Go on non-Unix platforms; the ten-file bundle is not one atomic filesystem transaction, so a crash can leave reports ahead of the graph marker. The build adds .gograph/ to an absent or regular enclosing Git-root .gitignore when available and falls back to the build target outside Git; it refuses a link or special file. A zero-file or zero-successful-parse build does not replace existing artifacts; parse failures and selection/security warnings are recorded in graph metadata and make status partial.
Queries and refreshes — graph-backed CLI analysis reads the last trusted, regular repository-confined graph.json with the current source-policy marker and replaces its serialized root with the selected project; commands whose contract reads source, Git, or other local state do so through their documented boundaries. MCP source-analysis tools check source-content digests, the build/module fingerprint, and newer usable persisted artifacts, adopt a newer compatible precise graph, and incrementally reparse changed packages after edits. Precise refreshes still recompute repository-wide CHA/SSA. When no usable artifact exists, persisted-index MCP tools use the startup fallback. Refreshes stay in memory by default. gograph mcp [path] --persist-refresh opts into publishing the latest successful refresh with the same graph-last protocol; 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 and normally records precise_fallback on the retained AST graph. A failed retry keeps an existing fresh successful precise artifact covering the same selected sources instead of downgrading it (ast identifies an explicitly requested AST build).

What it captures

Signal	How extracted
Functions, methods, structs, interfaces, types, variables, constants	AST `FuncDecl`, `TypeSpec`, `ValueSpec`
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`, `os.LookupEnv`, supported Viper `Get*`
Struct-field and package-global mutations	Direct assignments plus precise alias, compound, atomic/sync/wrapper, and channel evidence
Error and panic sites	`errors.New`, `fmt.Errorf`, sentinel declarations, `panic`
Concurrency primitives	`go` statements, channel sends, typed `Mutex`/`RWMutex`/`WaitGroup`/`Once` calls
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.5 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. Global Flags Global flags may appear before or after the command: --json: Structured output for query and composed-analysis commands. --files-only: Deduplicated paths for the commands listed under Output Modes; an empty result writes zero lines. --mermaid: Mermaid output for callers, callees, impact, endpoint, dependents, deps, path, and coupling. Bare gograph --mermaid is shorthand for gograph diagram. -i <message> / --intention <message>: Technical rationale recorded with CLI command telemetry. It is mandatory for analytical commands while an audit session is active; session, MCP startup, build, installation, help, version, stale, stats, capabilities, wiki, and doc commands do not require it. Request only one of --json, --files-only, or --mermaid; unsupported or conflicting output flags fail instead of being silently ignored. ...

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 under this server ID: io.github.ozgurcd/gograph The server ID is a Registry identifier, not a web address. You can inspect its active versions in the official Registry API. 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?#