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"

💡 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

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

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

💡 Note: 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.

Machine-readable output

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.

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