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:

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:

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.