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.

Explore the interactive no-install demo · Review the reproducible benchmark

See CLI/MCP query contracts for bounded result pages, snapshot-bound cursors, exact/possible impact, and change-evaluation status.

Companion projects: Scrinium provides repository-owned, evidence-backed knowledge for coding agents, while Rulefloor protects repository-local invariants by binding them to concrete tests and detecting drift. They are independent, optional tools: Scrinium can keep Gograph structural observations and Rulefloor validation results as separate evidence without treating either as proof of unrelated behavior or global project correctness.

Static analysis; no target-code execution. Default indexing parses Go source locally and does not call application services. Linked directories and linked/special files for extensions recognized by go/build are excluded; unrelated regular-file or dangling links with non-Go extensions are not Go tool inputs and do not block precise analysis. Graph-directed source reads remain confined to regular files beneath the analyzed repository, and linked/non-regular Go tool metadata (go.mod, go.sum, go.work, go.work.sum, and vendor/modules.txt) is rejected before toolchain invocation; an explicitly symlinked repository root remains supported. Applicable go.work use members may be sibling modules beneath the nearest real Git checkout; without that boundary they remain confined beneath the workspace directory. Each member directory, go.mod, and optional go.sum is validated before cmd/go starts. Gograph also reads project metadata such as .gitignore, graph/config JSON, and Git state. Indexing asks the installed Go toolchain for the effective build/module context; precise mode additionally performs package type loading, and doc runs go doc. Those operations follow your configured module/cache/network policy. Before repository package loading or go doc, applicable local module/workspace source trees are preflighted for links that cmd/go may inspect; .git and .gograph subtrees are excluded. Session telemetry is local under .gograph/sessions/; nothing is sent to gograph services.

Quick Start

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

# Confirm which installation will run and detect PATH shadowing
gograph doctor --json

# Build a type-enriched precise graph, then verify it
gograph build . --precise
gograph stats

# Optional CI contract: fail when precise enrichment falls back
gograph build . --precise --strict

# Optional: prioritize lower heap use on constrained hosts
gograph build . --precise --memory-mode=low --max-memory=1GiB

# Optional: include integration-tagged files and tests in this graph
gograph build . --precise --tags=integration

# Optional: omit unrelated broken package directories
gograph build . --precise --strict --exclude-dirs=legacy,examples/broken

# 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 cask 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 explore "YourSymbol" --compact # low-token discovery, identity/role, and complete evidence counts
gograph explore "YourSymbol"           # standard source + callers/callees + tests + exact identity impact
gograph explore "YourSymbol" --deep    # standard response + depth-3 exact evidence, package context, explanation
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. The update accepts only an absent or regular .gitignore; a repository-provided link is refused and its target is not modified. Go build constraints, explicit comma-separated --tags (or inherited GOFLAGS when the flag is absent), 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. Linked .go files, linked directories, and other non-regular recognized Go inputs are reported and excluded. Unrelated regular-file and dangling links with non-Go extensions (for example YAML configuration or TSV fixtures) are ignored by Go-tool preflight; linked/non-regular go.mod, go.sum, go.work, go.work.sum, and vendor/modules.txt entries are rejected before gograph or the Go toolchain reads them. Applicable go.work use members may be sibling modules beneath the nearest real Git checkout. Non-Git layouts retain workspace-directory confinement, nested Git boundaries are not crossed, and every member directory, go.mod, and optional go.sum is validated before cmd/go starts. .gograph itself must be a real directory, and graph.json must be a regular repository-confined file. Graphs with a missing or unsupported confinement policy marker must be rebuilt with the current binary before graph-backed commands use them. Older binaries do not enforce this boundary and should not be used to analyze untrusted repositories.

Each indexed source file stores a SHA-256 content digest. Rebuilds reparse all selected files in a changed package together and reuse parser records for unchanged packages; stats reports reused_files and rebuilt_packages. Precise builds reuse that AST work but still recompute repository-wide type/CHA/SSA enrichment so cross-package dispatch remains correct.

Low-memory mode preserves those graph semantics while using more aggressive garbage collection, reclaiming memory between production and test analysis, and avoiding a full JSON copy of the AST graph. --max-memory accepts integer byte sizes such as 1GB or 1GiB and requires --memory-mode=low. It is a soft Go-runtime memory target—not a hard RSS cap—so memory-mapped files, the executable, and Go toolchain subprocesses can make process memory exceed the requested value. Aggressive GC can increase CPU time, and a target that is too low may make the build much slower or fail; Gograph never silently reduces precision to meet it.

Precise fallback continues to exit zero by default for compatibility and is recorded in graph metadata. Add --strict with --precise when fallback must fail CI; Gograph still publishes or retains the diagnostic artifact before returning non-zero.

For precise builds blocked by unrelated directories, see directory exclusions. Use the same --exclude-dirs selection on gograph mcp startup; imported dependencies must still type-check. For symlinked skills, v1.7.2 supports --exclude-dirs=.claude/skills: directory links beneath that real directory are hidden from Go loading, without following their targets. Linked Go inputs and metadata remain protected. See the Codex MCP setup guide for registration and verification.

Machine-readable structural validation

External consumers can validate one closed structural predicate without parsing human CLI output:

gograph version --json
gograph validate --repo /work/project --binding-json '{"schema_version":"gograph.binding.v1","predicate":"symbol_exists","subject":{"language":"go","kind":"symbol","id":"example.com/project/internal/auth::Authorize"},"required_precision":"ast"}' --json

The version and result schemas are gograph.version.v1 and gograph.validation.v1; bindings use gograph.binding.v1. V1 supports only symbol_exists, package_imports, call_edge_exists, and type_implements. Validation is read-only and never builds or refreshes the graph. Exit 0 means pass, exit 1 means a conclusively evaluated fail, and exit 2 means cannot_evaluate or an invalid request.

Negative results require predicate-specific completeness: symbol and direct import absence need a current complete AST graph; implementation absence needs a current precise-complete graph; call absence additionally requires complete resolution of the subject's relevant call edges. Missing, stale, partial, ambiguous, or unresolved evidence degrades to cannot_evaluate; a precise_fallback graph may support AST presence but never evaluated absence. The result binds the exact graph bytes, selected source/build-context manifest, and canonical binding with SHA-256 fingerprints.

Gograph validates selected-build-context Go structure. It does not prove runtime behavior or business correctness. CHA edges are possible static targets, not runtime dispatch certainty. V1 excludes reachability, unstable or external symbol identities, unnamed types, and non-Go languages. See the exact machine-validation contract. Applicable local module/workspace source roots must remain beneath the explicit --repo root; v1 returns cannot_evaluate instead of widening that authority.

MCP refreshes stay in memory by default. To publish each successful refresh for CLI consumers and later server processes, start the server explicitly with:

gograph mcp . --persist-refresh
# Keep MCP startup and every later refresh on the integration-tagged selection:
gograph mcp . --tags=integration
# Optional low-memory policy for startup analysis and later refreshes:
gograph mcp . --memory-mode=low --max-memory=1GiB

This opt-in mode writes or overwrites .gograph/graph.json and the nine Markdown reports after a confirmed-fresh refresh. It does not modify .gitignore, so ignore .gograph/ yourself before enabling it when needed. The directory holds only the latest published state; it is not a per-branch cache. If no usable graph exists (including an unsafe or unsupported artifact), the startup auto-build is published before serving; a failure there prevents startup. A later tool-triggered publication failure makes that tool return an error, and the server retries the pending publication on another refresh-capable call without rebuilding the already-fresh in-memory graph. Writers coordinate through a local .gograph/.artifacts.lock file; an existing lock entry must be regular rather than a link or special file. Reports are replaced first and graph.json is replaced last as the publication commit marker; the complete ten-file bundle is not a single atomic filesystem transaction. Same-directory replacement is atomic on Unix-like systems; Go does not guarantee atomic rename semantics on non-Unix platforms. The lock file remains as operational coordination state in addition to the ten outputs.

Persisted graphs are bound to their effective Go environment and build selection. Start MCP with the same GOWORK, GOFLAGS, and --tags context used to build the graph; a mismatch is stale and must refresh successfully or return a diagnostic rather than silently serving incompatible facts. gograph doctor --json reports that repository diagnostic.

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):

Task	grep -rn	gograph	Observed output difference
Find callers of loadGraph	158 matching lines (comments, docs, vars)	56 AST-derived call-site rows	~65% fewer rows in that run
Locate symbol definitions	842 lines matching "Symbol"	83 true type/method declarations	~90% noise eliminated
Read one function body	cat displays 180+ lines of the whole file	source extracts the 12-line function	~93% fewer source lines in that run
Gather common symbol context	Separate node, source, caller, callee, and test queries	context bundles those fields	Five evidence types in one response

Key Features

Machine and Agent Workflows — explore provides bounded first-call discovery with ranked lexical matches, explicit symbol selection, source, callers, callees, tests, and exact identity-resolved impact; focused callers, callees, broader impact, reverse test coverage, stable identity, plan, review, flow, validation, and policy commands remain available. The MCP server registers 68 endpoints including four session lifecycle tools. Full command reference →

Federated Workspaces — model multiple checked-out repositories through independently fingerprinted repository graphs plus a small deterministic cross-repository overlay. Resolution scopes support alternative fleets such as OSS/CE without merging repository ownership. P0 resolves Go modules, ordinary cross-repository Go calls, and first-class HTTP contracts for workspace-wide status, query, path, and impact analysis. The four read-only workspace MCP tools return the same native result values as CLI --json; member refresh and overlay publication remain explicit CLI mutations. Workspace guide →

Native MCP Server — all 64 repository query, analysis, and workflow capabilities have project-MCP equivalents for Claude, Cursor, Copilot, and other MCP clients; four additional endpoints cover session lifecycle (68 project tools total). A separate workspace server provides status, query, path, and impact with the same native results as the corresponding CLI operations. The normal mapping is CLI <command> to MCP gograph_<command>; contract, boundaries --create, and session actions use the documented special mappings. CLI-only process/host/artifact operations are build, validate, doctor, gate, snapshot, plugin/hook installation, project/workspace MCP startup, workspace build/member refresh, and help. The standalone version command has no MCP tool, but gograph_capabilities reports the running server version. Transport presentation differs where appropriate, but paired operations share functional semantics. Complete CLI/MCP matrix →

Explicit Freshness Model — CLI graph-backed analysis reads the last trusted persisted graph. Its JSON envelope includes gograph.graph-state.v1, separating source (persisted/in_memory), freshness (current/stale), completeness (complete/partial), precision (ast/precise/fallback), refresh outcome, and persistence outcome; bounded diagnostics remain on the operation that produced them. Text stats and stale report the same persisted state. gograph stale compares selected source content digests plus the effective build/module fingerprint; mtimes are diagnostic only for current indexes. It is a tri-state predicate: exit 0 means current, 2 means stale, and 1 means an operational or JSON serialization error; a missing or unsupported source-policy marker is an explicit status-1 rebuild requirement. MCP source-analysis tools check the same freshness per call, adopt a newer persisted precise graph, and incrementally rebuild changed package ASTs in memory using the latest requested analysis mode. Refresh-backed tools preserve their compatibility text and add gograph.mcp-result.v1 structured content plus _meta.gograph_graph_state. Failed precise enrichment can serve a clearly marked current in-memory fallback, while an ordinary refresh failure can serve the last trusted stale graph; neither degraded result is silently published, and a mismatched effective Go environment still fails closed. MCP stale, default changes, and stats inspect the trusted persisted snapshot, or the startup auto-build fallback when no usable artifact exists. With --persist-refresh, that snapshot advances after a successful refresh; publication failures leave the fresh in-memory graph usable and explicitly report persistence.outcome=failed with a persistence diagnostic for retry.

Compact Composite Workflows — explore, context, plan, and explain combine source and graph evidence that would otherwise require several separate queries. explore is additive: specialized commands remain the complete, stable interfaces for focused analysis. 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 intentionally scan .env, key, certificate, or credential files. Linked directories and linked/special recognized Go build inputs are excluded; unrelated non-Go regular-file links are outside Go-tool preflight. On-demand source and snippet reads use a repository-rooted filesystem handle and accept only regular .go files without symlink components. Linked/non-regular Go module/workspace metadata, sums, and vendor/modules.txt are rejected before toolchain use. Applicable go.work members may be siblings inside the nearest real Git checkout and otherwise stay beneath the workspace directory; their directories plus module metadata are preflighted before cmd/go. Default/relative policy configs are project-confined; documented absolute config/output arguments are explicit operator-selected local locations. AI worktree directories (.claude/, .cursor/, .agents/) are excluded. The installed Go toolchain resolves effective build context during indexing; precise repository package loading and external go doc run only after a preflight that rejects source-tree links cmd/go may inspect across the selected root plus its effective module root, or the workspace root and member trees, excluding .git and .gograph. Dependency and toolchain resolution remain open-world under the user's Go environment.

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 — publication refuses a linked or non-directory .gograph; graph.json is staged and replaced last only after a successful parse (the same-directory rename is atomic on Unix-like systems), 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; version --json and validate ... --json use their dedicated machine schemas. The exact --files-only surface is listed in the command reference. Operational commands such as build, wiki, gate, snapshot, installation, and help use text output; doctor and workspace build/status/query/path/impact also accept --json, and session audit additionally supports raw JSON. CLI --mermaid renders callers, callees, impact, endpoint, dependents, deps, path, and coupling as fenced Mermaid. Their MCP equivalents accept mermaid=true and return the same Markdown-fenced Mermaid text; without it, each tool retains its normal response format.