## What is gograph?#

gograph is a CLI tool that walks a Go repository, parses every `.go` file with the standard AST, and stores the result as a structured graph in `.gograph/graph.json`. Every query reads from that graph — no re-parsing, no network calls, no external services.

    gograph build .                        # index the repo — fast, tolerates broken code
    gograph build . --precise              # type-checked CHA — use before refactors
    gograph callers ValidateToken          # who calls this?
    gograph plan HandleLogin               # safe-edit plan before changing a function
    gograph errorflow "invalid token"      # trace an error to the HTTP layer
    gograph changes --git main             # what changed since main?

### Real Command Output Example#

Here is the actual, exact output when querying `gograph` for callers of its index-loading function, `loadGraph`:

    $ 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 AI Agents (Massive Token Reduction & Context Savings)#

AI coding assistants and agent systems (like Claude Code, Cursor, Copilot, Google Antigravity, and OpenCode) are highly habituated to using standard Unix tools (`grep`, `find`) to search and navigate Go repositories. In large Go codebases, this is highly inaccurate, slow, and expensive.

gograph completely transforms this dynamic:

- No Search Noise: Generic `grep` returns hundreds of lines of mocks, test logs, and comments. gograph queries the compiled AST database directly, returning 100% accurate, ground-truth relationships.
- Dramatic Token Reduction: By replacing broad text scans with precise, symbol-focused graph queries, gograph drastically reduces the context size sent to the model, saving significant token overhead.
- Production-Proven Performance: In real-world production evaluations running swarms of 35 specialized Claude Code agents on large Go codebases, replacing raw `grep` across 80+ endpoints with gograph’s pruned, AST-accurate context dropped the measured hallucination rate from ~12% down to 2%.

## Install#

Homebrew

    brew install ozgurcd/tap/gograph

Go install

    go install github.com/ozgurcd/gograph@latest

From source

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

## How it works#

1. `gograph build .` — walks all `.go` files concurrently, extracts symbols, call edges, imports, HTTP routes, SQL queries, environment reads, struct fields, error declarations, and concurrency primitives. Writes everything to `.gograph/graph.json` and nine Markdown reports.
2. Query commands — read from `graph.json` in memory. All queries are millisecond-fast regardless of repository size.
3. `--precise` mode — runs the full Go type checker (CHA) on top of the AST pass for accurate interface dispatch resolution. Slower, requires compilable code.

## 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{...}`

## Why use it?#

Standard tooling — `grep`, `find`, language servers — answer file-level questions. gograph answers structural questions:

- 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?

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 fast, AST-aware Go codebase analysis tool and MCP server. Query call graphs, dependency trees, interface implementers, and error flows in milliseconds — from your terminal or any AI agent.

## 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@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: ...

## 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/. 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. ...

## AI Agent Integration & Token Reduction

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. ...

## 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: ...