gograph

gograph

Symbol queries accept path/to/file.go:Name, including path/to/file.go:Receiver.Method, or an import-qualified file path when a short name is ambiguous. source prints exact selectors for ambiguous matches. Supported declaration tools and named exceptions are listed in the selector contract. Queries include struct fields; query --no-tests excludes test-file rows. Precise mutation queries recover the type of fields assigned on returned values. Routes retain constant and unresolved path registrations; precise builds resolve constants across packages, including net/http method patterns. tests --transitive --files-only prints unique file paths, matching the files in the MCP transitive report.

Graph-state output and capabilities expose freshness_context: CLI freshness checks use the querying process's Go context, including GOFLAGS; MCP uses its startup context and explicit tags. A context mismatch remains stale, even when source bytes have not changed. No environment values are printed. Precise indexes include package-level constant references in usages and query, including comparisons, switch cases, composite values, and function arguments. Typed enum-like constants retain their declaration identity; local shadows are excluded. query labels these reference sites as usage rows. AST-only graphs do not claim type-resolved constant usages. review uses the same test attribution as context. Rebuild after upgrading.

review --uncommitted includes deleted declarations from changes --git HEAD and explicitly leaves historical callers, tests and risk unevaluated. Other current-graph traversal commands retain their deletion refusal. Builds explain when an enclosing Git repository ignores the requested directory.

Uncommitted plan/review skip blank-identifier declarations such as var _ I = (*T)(nil) during symbol traversal. Review keeps their declaration evidence and names the limit; changes --git HEAD still lists them.

Session audits list invocation errors separately from operational failures and exclude them from compliance scoring. Composability measures the mix of composed and raw query commands; it does not measure answer correctness or token savings.

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](https://gograph.identuum.ai/demo/) · [Review the reproducible benchmark](docs/benchmarking.md)

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 ne