Welcome to the gograph documentation portal!
gograph is a developer and AI agent tool built to index, trace, and query Go codebases using AST-derived call graphs and dependency maps.
🗺️ Documentation Map#
Explore the documentation across five primary categories:
Set up gograph on your system, initialize your first repository graph index, and run basic queries.
- Topics: Homebrew install, Go build, compilation requirements,
stats verification, stale checks.
An exhaustive command manual detailing all gograph capabilities.
- Topics: Indexing commands, Search & Navigation, Call Graph traversal, Interface resolution, Packages & Imports, security flow analysis, Concurrency mapping, custom error flows, and composite literals mapping.
Connect gograph with AI coding assistants (like Claude Code, Cursor, and custom LLM workflows) to reduce broad file reads and unsupported structural guesses.
- Topics: MCP stdio setup, in-memory refresh behavior, Claude Desktop/plugin configuration, and the Claude Code PreToolUse hook guard.
Discover safe development workflows and optimization protocols.
- Topics: Onboarding to fresh codebases, the plan-to-review edit lifecycle, and package refactoring dependencies extraction.
Install a platform-specific MCP Bundle from the preview Registry and select the
Go project directory it analyzes.
- Topics: MCPB versus Homebrew/
go install, six release targets, local data handling, and the current CPU-selection limitation.
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.
...
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.
...
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.
...
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:
...
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.
...