Welcome to the gograph documentation portal!
gograph is a developer and AI agent tool built to index, trace, and query Go codebases using AST-accurate call graphs and dependency maps.
🗺️ Documentation Map#
Explore the documentation across four 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, Concurrency mapping, custom error flows, and composite literals mapping.
Connect gograph with AI coding assistants (like Claude Code, Cursor, and custom LLM workflows) to save context tokens and drop hallucination rates.
- Topics: Model Context Protocol (MCP) server stdio setup, auto-building, Claude desktop plugin installation, and the smart Pre-Tool-Use 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.
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@latest From source
git clone https://github.com/ozgurcd/gograph cd gograph make build # produces bin/gograph sudo make install # copies to /usr/local/bin Step 1 — Build the graph Navigate to the root of any Go module and run:
gograph build . This walks every .go file, extracts the AST, and writes:
...
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/.
Arguments: path (optional, defaults to .) Flags: --precise: Enables type-checked Class Hierarchy Analysis (CHA) using Go’s type-checker to resolve dynamic interface dispatches to concrete caller/callee relationships. Slower, requires code to be compilable. stale gograph stale Checks if any .go source files in the repository are newer than .gograph/graph.json. Returns a list of files that have been modified since the last build.
...
gograph is built from the ground up to be an agent-first tool. While humans can query the CLI, the primary design target is AI coding agents (such as Claude Code, Cursor, Copilot, Google Antigravity, or OpenCode) that need accurate, structured repository intelligence without context-window inflation.
🚫 The Problem: Unix Tools are Expensive & Blind In modern AI agent loops, models are highly habituated to using standard Unix text-processing commands (grep, find, sed) to understand and navigate code. For Go, this is an inefficient, token-expensive, and error-prone anti-pattern.
...
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:
...