Gograph

gograph

Give Go coding agents a compiler-aware map for safer refactors.

gograph builds a local structural graph of your Go repository, with optional type-checked CHA/SSA enrichment. Its CLI and MCP workflows help coding agents trace callers and interface implementations, plan change impact, and enforce architecture without embeddings or a hosted code index.

Static analysis; no target-code execution. Default indexing parses Go source locally and does not call application services. It also reads project metadata such as go.mod, .gitignore, graph/config JSON, and Git state. Precise mode and doc invoke the local Go toolchain, which follows your configured module/cache/network policy. Session telemetry is local under .gograph/sessions/; nothing is sent to gograph services.

Quick Start

# Install
brew install ozgurcd/tap/gograph
# or: go install github.com/ozgurcd/gograph/cmd/gograph@latest

# Build a fast AST graph, then verify it
gograph build .
gograph stats

# Start with repository-wide results that require no guessed symbol
gograph summary
gograph hotspot --top 5
gograph flow --no-tests

Homebrew and go install install the normal gograph CLI. MCP clients that support MCP Bundles can instead discover the local stdio server in the official MCP Registry as io.github.ozgurcd/gograph. Registry/MCPB installation is a separate distribution path; it does not install the Homebrew formula or configure the Claude Code marketplace plugin. The Registry is currently in preview. See Official MCP Registry and MCPB installation for client support, target selection, and current limitations.

Choose a real function or method shown by summary, hotspot, or gograph complexity, then substitute its name below:

gograph context "YourSymbol" # source + callers + callees + tests

# For compilable repositories, enrich the graph before a major refactor
gograph build . --precise
gograph plan "YourSymbol"

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 replacing artifacts if no Go files are found or no source file parses successfully. Go build constraints, cmd/go package-directory rules, generated sources, module-mode ignore directives, and Git ignores use the same scanner policy for building, freshness checks, and change detection.

Why gograph?

Illustrative point-in-time output comparison from an earlier gograph revision (counts vary as the repository evolves; these commands return different kinds of evidence):

Key Features

61 Query and Analysis Capabilities — callers, callees, impact, context, plan, review, flow, errorflow, orphans, hotspot, coupling, and more. The MCP server registers 65 endpoints including four session lifecycle tools. Full command reference →

Native MCP Server — every query and analysis capability has an MCP endpoint for Claude, Cursor, Copilot, and other MCP clients. Host integration and CI artifact commands (build, gate, snapshot, plugin/hook installation, server startup, help, and version) remain CLI-only.

Explicit Freshness Model — CLI analysis reads the last persisted graph. MCP source-analysis tools check freshness per call, adopt a newer persisted precise graph, and rebuild in memory after edits using the latest requested analysis mode. MCP stale, default changes, and stats inspect the persisted snapshot.

Compact Composite Workflows — context, plan, and explain combine source and graph evidence that would otherwise require several separate queries. Actual tool-call and token savings depend on the repository and task.

Narrow by Design — never runs target repository binaries or tests and does not read .env, key, certificate, or credential files. AI worktree directories (.claude/, .cursor/, .agents/) are excluded. Precise analysis and external documentation use the installed Go toolchain.

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

Security Flow Analysis — flow follows potential HTTP request, decoded JSON, and environment data across assignments and function calls to SQL query text, process execution, filesystem paths, and outbound HTTP targets. Findings include severity, confidence, and source-to-sink path steps; MCP exposes the same analysis as gograph_flow.

Integrity-Aware Indexing — graph.json is atomically replaced only after a successful parse, records complete/partial build health and ast/precise/precise_fallback analysis status, and exposes both through gograph stats. gate refuses to evaluate a stale graph.

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

Query and composed-analysis commands support --json; result-list queries also support --files-only. Operational commands such as build, wiki, gate, snapshot, sessions, installation, help, and version use text output.

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.

gograph flow includes test files by default; add --no-tests for production-only results. It automatically reads .gograph/flow.json when present, or accepts --config <path> for another JSON file inside the graph root. Sanitizers apply to a function's return value and can be scoped to selected sink kinds:

{
  "sanitizers": [
    { "function": "security.CleanPath", "for": ["filesystem"] },
    { "function": "security.ValidateURL", "for": ["outbound_http"] }
  ]
}

Omit for to trust the return value for every sink kind. function accepts the call spelling or a fully-qualified symbol ID; use the fully-qualified form when names collide. A validator that returns only bool or error does not sanitize the original input; wrap validation in a function that returns the trusted value if that is the intended policy.

AI Agent Integration

Official MCP Registry (preview): MCPB-capable clients can discover io.github.ozgurcd/gograph. The bundle asks for the root directory of the Go project and launches the bundled executable with separate arguments equivalent to gograph mcp <project-directory>. Releases provide macOS, Linux, and Windows bundles for both amd64 and arm64. The current Registry package schema cannot select by CPU architecture, so choose the asset whose filename matches the host; do not assume a client will select it automatically. All analysis still runs locally over stdio, with no hosted gograph service or remote telemetry.

Desktop config, shared rules, and Claude Code hook setup:

gograph add-claude-plugin

This registers the Claude Desktop MCP server, injects shared CLAUDE.md steering rules, and installs a Claude Code PreToolUse hook. For Claude Code MCP registration, also run the command printed by the installer: `claude mcp

…