Gograph

gograph

Stop burning tokens on grep. Give your AI agent a graph.

gograph builds a local, AST-aware call graph of your Go repository and exposes 50+ query tools via CLI and MCP so coding agents can navigate packages, symbols, call chains, routes, SQL, env vars, and tests — without reading raw files.

Zero network. Zero execution. Zero secrets read. gograph is purely static analysis — it never runs your code, makes API calls, or opens non-.go files.

Quick Start

# Install
brew install ozgurcd/tap/gograph

# Build the graph
gograph build . --precise

# Try it — who calls ValidateToken?
gograph callers "ValidateToken"

# Full context in ONE call (node + source + callers + callees + tests)
gograph context "ValidateToken"

# Change plan before editing (callers, tests, routes, SQL, env risk)
gograph plan "ValidateToken"

Build artifacts are written under the target .gograph/ directory. gograph adds .gograph/ to the enclosing Git repository root .gitignore when available, falls back to the build target .gitignore outside Git, and exits without writing artifacts if no Go files are found after ignore filtering.

Why gograph?

Benchmarked on gograph's own codebase (70 files, 518 symbols, 16 packages):

Key Features

50+ Query Tools — callers, callees, impact, context, plan, review, errorflow, orphans, hotspot, coupling, and more. Full command reference →

Native MCP Server — all tools available as MCP endpoints for Claude, Cursor, Copilot, and any MCP-compatible agent. One command setup: gograph add-claude-plugin

Token-Saving Composites — context replaces 5 calls. plan replaces 8. explain synthesizes architectural narratives. Built to minimize agent round-trips.

Safe by Design — no network, no code execution, no secrets, no .env files read. AI worktree directories (.claude/, .cursor/, .agents/) auto-excluded.

Architecture Enforcement — boundary rules, API drift detection, complexity gates, dead code sweeps, god-object detection, coupling analysis. Run in CI with gograph gate.

Agent Compliance Auditing — session telemetry tracks whether agents run plan before edits and review after. Grades agent behavior A–F with actionable recommendations.

Command Reference

All commands support --json for machine-readable output and --files-only for flat file lists.

Full command reference with examples: gograph.identuum.ai/docs/command-reference

Define boundaries in .gograph/boundaries.json:

{
  "layers": [
    { "name": "domain", "packages": ["internal/domain/**"], "may_import": [] },
    { "name": "handler", "packages": ["internal/handler/**"], "may_import": ["internal/service/**", "internal/domain/**"] }
  ]
}

Run gograph boundaries — exits with code 1 on violation. Works in CI/CD.

AI Agent Integration

One-command setup (Claude Desktop + Claude Code):

gograph add-claude-plugin

This registers the MCP server, injects CLAUDE.md steering rules, and installs a PreToolUse hook that redirects grep on Go symbols to gograph tools.

Alternative — install via Claude Code plugin marketplace:

/plugin marketplace add ozgurcd/gograph
/plugin install gograph@gograph

Discovers gograph through Claude Code's plugin marketplace and ships a SKILL.md that auto-activates on Go work, teaching the agent the mandatory workflow (capabilities → build → plan → context → review) and that grep/rg/find must not be used for Go symbol search.

You still need the gograph binary installed (brew install ozgurcd/tap/gograph or go install github.com/ozgurcd/gograph@latest). Use gograph add-claude-plugin above for the full one-command bootstrap (MCP wiring + CLAUDE.md rules + PreToolUse hook). Use the plugin marketplace when you'd rather discover and install gograph from inside Claude Code's plugin UI.

Other agents (Cursor, Copilot, Antigravity, etc.):

gograph mcp .   # Run as MCP server over stdio

Add to your .cursorrules or AI system prompt:

Before answering architecture or repository questions, inspect the available gograph_* MCP tools and use them instead of grep/find. Run gograph capabilities first.

All commands support --json for machine-readable output:

gograph callers "ValidateToken" --json
# → {"schema_version": "1", "command": "callers", "status": "ok", "count": 2, "results": [...]}

For full integration guides, see docs/coding-agent-usage.md.

Zero-cost orientation with llm-wiki/: Run gograph wiki once per session to generate a directory of machine-first markdown pages — overview, architecture diagram, hotspots, routes, env vars, error sites, concurrency, per-package docs, and the full API surface. Agents read these pages instead of issuing dozens of individual tool calls:

gograph build . --precise
gograph wiki                 # writes to ./llm-wiki/
# then read: llm-wiki/README.md → project.md → rules.md → agent-contract.md → overview.md

Add llm-wiki/ to .gitignore — these files are regenerated each session.

Example Output

When you run gograph build ., the generated GRAPH_REPORT.md gives your AI a condensed context map:

External Dependencies (Tech Stack)

Important Symbols (Top by outgoing calls)

Why not use a Language Server (gopls)?

gopls is optimized for human IDEs. gograph is optimized for terminal-based LLMs:

1. Protocol Mismatch — gopls returns file:line:col coordinates. Agents must then burn tokens running cat/sed to read the actual code. gograph extracts the exact structural slice and formats it as Markdown.
2. Graph-Level Diagnostics — gopls does hover and go-to-definition. gograph does reverse-BFS error tracing, full blast radius analysis, and PR-level change plans across the entire call graph.
3. Composable Intelligence — gopls answers one question at a time. gograph context bundles node + source + callers + callees + tests in a single call. gograph plan aggregates impact, routes, SQL, env, and test risk into one checklist.

• Default mode uses Go AST parsing and best-effort heuristics. Tolerates incomplete or non-compiling repositories.
• Precise mode uses type-checked enrichment and requires compilable packages.
• Heuristic extractors (routes, SQL, tests, error mapping) are navigation aids, not authoritative program analysis.

• No multi-language parsing
• No AI/model API calls
• No embeddings or SaaS backend
• No telemetry
• No replacement for compiler/type-checker correctness

Contributing

Pull requests welcome! See CONTRIBUTING.md for build, test, and contribution guidelines.

Language Support: gograph currently parses Go only. The architecture is extensible — if you want to add Python, TypeScript, Rust, etc., please open an issue first.

License

MIT — see LICENSE.