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:

• .gograph/graph.json — the machine-readable graph (all queries read from this)
• .gograph/GRAPH_REPORT.md — master index report
• .gograph/graph-symbols.md — all symbols
• .gograph/graph-routes.md — HTTP routes
• .gograph/graph-sql.md — SQL queries
• .gograph/graph-errors.md — error declarations
• .gograph/graph-deps.md — package dependencies
• .gograph/graph-concurrency.md — concurrency primitives
• .gograph/graph-config.md — environment reads
• .gograph/graph-tests.md — test edge mapping

.gograph/ is automatically added to .gitignore.

Precise mode

gograph build . --precise

Runs the full Go type checker on top of the AST pass. This enables Class Hierarchy Analysis (CHA) for accurate interface dispatch resolution — calls through interface variables are resolved to their concrete implementations. Slower, requires compilable code. Use before major refactors or blast-radius analysis.

When to use which:

Step 2 — Check the index

gograph stats

Prints schema version, build timestamp, and counts:

schema_version: 2
generated_at:   2026-05-22T18:00:00Z
packages:       24
files:          187
symbols:        1843
calls:          6201
imports:        412
routes:         38
sqls:           29
env_reads:      14
test_edges:     522

gograph stale

Lists source files that are newer than graph.json. Run this before any structural analysis to confirm the index is current. Rebuild if any files are listed.

Step 3 — First queries

# Find a symbol
gograph query ValidateToken

# Read its source
gograph source ValidateToken

# Who calls it?
gograph callers ValidateToken

# What does it call?
gograph callees ValidateToken

# Full blast radius
gograph impact ValidateToken

# Before editing it
gograph plan ValidateToken

Example: Reading Symbol Source Code

Running gograph source directly against the codebase returns only the exact AST-extracted code block of the target symbol:

$ gograph source normalizeSymbolName

// github.com/ozgurcd/gograph/internal/search::normalizeSymbolName (internal/search/advanced.go:12-21)
func normalizeSymbolName(name string) string {
	name = strings.TrimPrefix(name, "(")
	if idx := strings.Index(name, ")."); idx >= 0 {
		name = name[idx+2:]
	}
	if idx := strings.LastIndex(name, "."); idx >= 0 {
		name = name[idx+1:]
	}
	return strings.ToLower(name)
}

Output formats

All query commands support three output modes:

gograph callers Foo              # text: [kind] Name — detail  (file:line)
gograph callers Foo --json       # JSON envelope: {"ok":true,"cmd":"callers","query":"Foo","count":N,"data":[...]}
gograph callers Foo --files-only # flat list of unique file paths

Use --json for scripting and AI agent pipelines. Use --files-only to get a checklist of affected files without printing every result.

Rebuilding

The graph does not auto-update. Rebuild whenever source files change:

gograph build .           # fast rebuild, tolerates broken code
gograph build . --precise # type-checked rebuild (before big refactors)

You can check whether a rebuild is needed:

gograph stale