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, default in-memory refreshes, opt-in artifact publication, CLI/MCP Mermaid output, 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.27.0 or later A Go module repository (go.mod present) Install Homebrew (recommended)
brew install --cask 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.
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.
...
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 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.
...