gograph
gograph is a local, compiler-aware static analysis server for Go repositories — it builds a structural graph (AST, optionally type-checked CHA/SSA) and exposes ~70 MCP tools for navigation, change impact, architecture enforcement, security review, and agent session auditing, without executing target code or using embeddings.
Navigation & discovery —
query,explore,context,source,node,skeleton,focus,summary,doc(go doc wrapper),strings(string-literal search).Call graph —
callers,callees,path,impact(transitive blast radius),hotspot(fan-in ranking),returnusage.Change analysis —
plan(pre-edit),review(post-edit),risk(0–100 score),changes(declaration fingerprints vs git ref),api(exported-surface drift).Architecture & quality —
boundaries/boundaries_create(layer rules),coupling,complexity,godobj,orphans,arity,diagram(Mermaid),check(policy suite).Types & structs —
fields,implementers,interfaces,embeds,constructors,literals,usages,mutate,schema(ORM table tags).Infrastructure inventory —
routes,endpoint(route → handler → SQL/env slice),sql(static PostgreSQL),envs,errors,errorflow/trace,concurrency,globals,httpcalls,deps,dependents,imports.Security —
flow: untrusted-source → sink (SQL, exec, filesystem, outbound HTTP) path findings with severity/confidence and sanitizer policy.Testing —
tests(direct & transitive attribution),coverage(test → product symbols),untested,fixtures,mocks.Graph health —
stale,stats,capabilities,summary; freshness/precision state reported per call.Agent workflow —
session_create/session_end/session_audit/session_cleanupfor compliance grading (A–F), pluswikito generate anllm-wiki/orientation bundle.Safety — read-only by default, repository-confined file access, no target-code execution, no remote telemetry; only
boundaries_create,wiki, and session tools mutate local files.
Allows analysis of Go projects using the Gin framework, including extracting HTTP routes and endpoint call chains.
Provides tools for analyzing Go repositories using Git metadata, including comparing symbols against Git refs, detecting uncommitted changes, and computing blast radius of changes since a baseline.
Generates Mermaid flowchart diagrams for visualizing call graphs, package dependencies, and coupling in Go code.
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. file.go:Name never matches a method; methods need
file.go:Receiver.Method. source prints exact selectors for ambiguous
matches, and every printed selector resolves to exactly one declaration.
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 · 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/buildare 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, andvendor/modules.txt) is rejected before toolchain invocation; an explicitly symlinked repository root remains supported. Applicablego.work usemembers 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 optionalgo.sumis validated beforecmd/gostarts. 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, anddocrunsgo doc. Those operations follow your configured module/cache/network policy. Before repository package loading orgo doc, applicable local module/workspace source trees are preflighted for links thatcmd/gomay inspect;.gitand.gographsubtrees 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-testsHomebrew 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.
Related MCP server: Context Zero Engine
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"}' --jsonThe version and result schemas are gograph.version.v1 and
gograph.validation.v1; bindings use gograph.binding.v1. V1 supports
symbol_exists, package_imports, call_edge_exists, type_implements, and
the policy predicates imports_only_from, callers_only_from and
call_arg_constant, which report every violating file:line.
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=1GiBThis 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 |
|
| Observed output difference |
Find callers of | 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 |
|
| ~93% fewer source lines in that run |
Gather common symbol context | Separate node, source, caller, callee, and test queries |
| 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 70 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 66 repository query, analysis, and workflow capabilities have project-MCP equivalents for Claude, Cursor, Copilot, and other MCP clients; four additional endpoints cover session lifecycle (70 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 return their answer once, as compact JSON text without structuredContent, and attach _meta.gograph_graph_state; a stale or degraded graph is also named in the text. 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.
Audit sessions belong to an explicit caller. gograph session create task prints
the session ID; pass it on subsequent CLI commands with --session-id ID or
GOGRAPH_SESSION=ID. The flag overrides the environment. Selected analytical
commands retain the --intention requirement and existing audit grades. Agent
shells usually do not keep GOGRAPH_SESSION between commands, so a CLI command
without a selector uses the repository's only active session when this host's CLI
created it; that covers build, plan, review, and session end. When
several sessions are active, or the only one is MCP-owned, from another host, or
lacks owner metadata, nothing is adopted: read-only commands then require no
intention and never write to another caller's audit. gograph session end ID
ends a named session.
A session its job forgot cannot block later jobs: every CLI command and MCP
call first ends other callers' abandoned sessions, meaning CLI sessions with no
activity for GOGRAPH_SESSION_IDLE_LIMIT (a Go duration, default 2h; 0 or
off disables) and sessions of MCP servers that have exited on this host. It
prints each one it ends on stderr. Refused calls do not count as activity, and
a call's own selected session is never ended. The forgotten owner's next call
reports that its session was ended as abandoned. Independent callers may create separate sessions concurrently.
Repository writes and session end/cleanup refuse while another caller owns an
active session, naming that session. Ending an owned session remains possible
while other owners are active. Unset GOGRAPH_SESSION after ending it.
MCP tools accept session_id and intention per request. Use the ID returned by
gograph_session_create; analytical owner calls require a rationale. The server
does not inherit GOGRAPH_SESSION, so sharing one MCP process does not merge
callers. Default in-memory refresh remains read-only; --persist-refresh calls
are guarded as writes. Session IDs are cooperative attribution selectors, not
credentials or an OS-user security boundary. Older active sessions can be
selected explicitly by their existing ID. See the session design.
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.
Category | Commands | What it does |
Indexing |
| Parse AST, optionally require precise success or prioritize lower heap use, write graph, check freshness and health. |
Machine Validation |
| Versioned exact structural and policy predicates with tri-state outcomes; release notes for the running binary. |
Navigation |
| Find symbols, trace call chains, extract source. |
Context |
| Bundled structural data in one call. Token savers. |
Change Analysis |
| Pre-edit planning, post-edit review, risk analysis, blast radius, drift. |
Architecture |
| Quality gates, dead code, coupling, god objects. Policies live in the committable |
Types & Structs |
| Struct fields, interface satisfaction, type usage. |
Infrastructure |
| Bounded CLI/MCP route and PostgreSQL static SQL pages with cursor continuation, module selectors, explicit test controls, and structured filtering; plus env vars, concurrency, outbound HTTP calls, and imports. |
Security |
| Potential untrusted-data paths to SQL, process, filesystem, and outbound HTTP sinks, plus policy-defined sources, sinks and argument sanitizers; constant non-shell programs are |
Testing |
| Direct and transitive reverse exact/possible static test attribution, runnable per-package |
Error Tracing |
| Reverse-BFS from error strings to HTTP entry points. |
Diagnostics |
| Install/PATH plus current graph freshness/capability diagnostics, hotspots, return usage, API signatures, Mermaid diagrams. |
CI/CD |
| Policy checks, threshold enforcement, metric snapshots. |
Telemetry |
| Agent compliance tracking and grading (A–F). |
LLM-Wiki |
| Generate |
Summary |
| Single-call codebase briefing: top 3 hotspots, worst instability package, highest complexity function, orphan count, god-object count. Replaces 5 separate calls. |
Stable IDs |
| Print and re-resolve module/package/receiver/name identity that survives line shifts and file moves inside a package; package disambiguates external-test collisions. |
Reverse Attribution |
| Transitive product-symbol set for one unambiguous test, with stable-ID paths and exact/possible propagation. Static evidence only—not runtime or branch coverage. |
Tests reaching a symbol |
| Versioned reverse attribution: a summary by depth and resolution, then 50 tests per page nearest first, each with a representative stable-ID path to one product symbol. Default |
Tests to run |
| Which tests to run for a change: per package, anchored |
Untested |
| Called production symbols without an exact transitive test path, |
Uncovered changes |
| Changed lines of non-test Go files that a coverage profile shows were never executed, as exact ranges. |
Doc |
|
|
Precise implementers results merge type-checked production types with
AST-discovered test-file fakes; --test-only/MCP test_only=true returns only
the latter. Direct tests lookup accepts Receiver.Method (including pointer
receivers) or a stable ID. usages covers signature/field/interface references
and Foo{...} construction. Precise indexes also include package variables and
constants referenced in expressions; literals remains the focused
construction-only view.
SQL extraction includes direct literals and statically resolvable local or
same-file package const/var declarations, straight-line assignments, and
bounded string concatenations. Runtime-generated SQL remains excluded. Route and SQL JSON are
paged row censuses; --files-only follows all pages but emits a complete
deduplicated file census, not every row.
Full command reference with examples: gograph.identuum.ai/docs/command-reference
Define boundaries in the committable gograph/boundaries.json (.gograph/boundaries.json, which gograph git-ignores, is still read when no committed file exists):
{
"layers": [
{ "name": "domain", "packages": ["internal/domain/**"], "may_import": [] },
{ "name": "handler", "packages": ["internal/handler/**"], "may_import": ["internal/service/**", "internal/domain/**"] }
]
}Run gograph stale (and rebuild when stale) before gograph boundaries; the
CLI evaluates the persisted graph and exits with code 1 on violation. The
default policy is gograph/boundaries.json, else .gograph/boundaries.json; use --config PATH for another
regular, repository-confined policy. MCP uses the same evaluation after its
normal source refresh. Works in CI/CD.
gograph flow includes test files by default; add --no-tests for production-only results. It automatically reads gograph/flow.json (else .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.
The Registry bundle and installer-generated MCP registrations intentionally omit
--persist-refresh, keeping disk publication off by default. Use a custom
local MCP command if you explicitly want that behavior.
Desktop config, shared rules, and Claude Code hook setup:
gograph add-claude-pluginThis registers the Claude Desktop MCP server, injects shared CLAUDE.md steering rules, and installs a Claude Code PreToolUse hook. The hook redirects Go-symbol searches only when an effective search target belongs to a repository with a .gograph index, so unindexed folders in multi-root workspaces remain unaffected. For Claude Code MCP registration, also run the command printed by the installer: claude mcp add gograph -- gograph mcp .. The installer exits non-zero when any installation step fails.
Alternative — install via Claude Code plugin marketplace:
/plugin marketplace add ozgurcd/gograph
/plugin install gograph@gographDiscovers gograph through Claude Code's plugin marketplace and ships a SKILL.md that auto-activates on Go work, teaching the agent the workflow (doctor --json → capabilities → stats → plan → context → edit → review), when a durable precise CLI build is useful, when to use structural queries, and when to verify with gopls or targeted text/source search.
You still need the gograph binary installed (brew install --cask ozgurcd/tap/gograph or go install github.com/ozgurcd/gograph/cmd/gograph@latest). Use gograph add-claude-plugin for Claude Desktop MCP wiring plus shared rules and the Claude Code hook; register the Claude Code MCP server with the printed claude mcp add command. Use the plugin marketplace when you prefer discovery from Claude Code's plugin UI.
Other agents (Cursor, Copilot, Antigravity, etc.):
gograph mcp . # stdio server; refreshes stay in memory
gograph mcp . --persist-refresh # opt in to publishing refreshed artifacts
gograph mcp . --tags=integration # retain the same tagged context on every refresh
gograph mcp . --memory-mode=low --max-memory=1GiB # same low-memory refresh policy as CLI buildsAdd to your .cursorrules or AI system prompt:
Before answering architecture or repository questions, inspect the available
gograph_*MCP tools and rungograph capabilities. Prefer gograph for supported structural queries; usegoplsor targeted source/text search when results are ambiguous, precision fell back, or a known source call is missing.
Query and composed-analysis commands support --json for machine-readable output:
gograph callers "YourSymbol" --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/
# generated orientation starts at: llm-wiki/overview.md
# if maintained governance pages exist, read:
# llm-wiki/index.md → project.md → agent-rules.md → agent-contract.mdAdd generated wiki output to .gitignore when it is disposable. Do not
overwrite a repository's maintained or Scrinium-protected agent-rules.md;
propose governed changes through that repository's documented workflow.
Regeneration removes only obsolete package pages that match Gograph's generated
signature; custom package pages and packages/README.md are preserved.
Example Output
When you run gograph build ., the generated GRAPH_REPORT.md gives your AI a condensed context map:
External Dependencies (Tech Stack)
Module | Version |
|
|
|
|
Important Symbols (Top by outgoing calls)
Symbol | Kind | File | Line | Calls out |
| method |
| 42 | 18 |
| function |
| 12 | 14 |
How does gograph complement gopls?
gopls is the Go project's
compiler-backed language server. It provides live workspace diagnostics,
navigation, references, implementations, refactoring support, and an
experimental MCP server. It should remain the first choice for editor and
compiler-aware workspace operations.
gograph adds a different layer for repository and agent workflows:
Persisted snapshots — CLI analysis can inspect a stable graph artifact, while MCP refreshes source-analysis state and preserves the requested precision mode.
Repository-level analyses — change impact, reachability, routes, SQL, environment reads, security-flow candidates, coupling, and policy gates are represented together.
Composed responses —
context,plan,review, andsummarypackage related evidence for agent workflows rather than exposing only one language operation at a time.
Use gopls for live compiler-backed navigation and refactoring, rg for text
and non-Go searches, and gograph when a persisted repository graph or composed
change-analysis workflow is useful. See the benchmark guidance
for how to measure these different workflows without assuming one tool is a
drop-in replacement for another.
Default mode uses Go AST parsing and best-effort heuristics. Tolerates incomplete or non-compiling repositories.
Repository source boundary excludes linked directories plus linked/special recognized Go build inputs before build selection, while unrelated regular-file or dangling non-Go links do not block precision. It supplies confined bytes to the AST parser and confines later
source, caller/callee snippet, complexity, and changed-file reads to regular repository files. Linked/non-regulargo.mod,go.sum,go.work,go.work.sum, andvendor/modules.txtmetadata is rejected before gograph or the Go toolchain reads it. Applicablego.work usepaths may select sibling modules beneath the nearest real Git checkout; without one they remain beneath their workspace directory. Nested Git boundaries are not crossed, and member directories,go.mod, and optionalgo.sumare validated beforecmd/go. Precise loading anddocpreflight the selected root plus its effective module root, or the workspace root and every member tree;.gitand.gographare excluded from that source-tree walk. Persistedgraph.jsonis also read through this boundary,.gographmust be a real directory, and an explicitly symlinked repository root is allowed. Missing or unsupported source-policy markers and artifacts larger than 512 MiB are rebuild-required, and serialized graph roots are never trusted. Saved baseline graphs must be regular non-linked files inside the selected project with the exact marker and size bound. Default/relative check and flow configs, boundaries, gate config, and repository-controlled session/snapshot/wiki mutations reject linked path components; documented absolute config/wiki locations are explicit operator selections. Use the current binary for untrusted repositories.Precise mode attempts type-checked production enrichment and needs compilable, build-selected packages for CHA/SSA results. SSA bodies are built for selected repository packages, not the full transitive dependency closure; imported types and local external-call references remain available without dependency-body call graphs or their source-less wrapper noise. If enrichment fails or omits an indexed non-test source file, the command warns, publishes the AST graph, and records
precise_fallback; if a fresh successful precise artifact already covers the same sources, a failed retry keeps that artifact instead. Default fallback remains exit zero for compatibility;--strictrequires--preciseand returns non-zero after publication or retention. Successful and AST-only builds recordpreciseandastrespectively. Test packages are loaded in a separate non-fatal typed pass: broken tests yieldtyped_partialtest-call attribution without downgrading successful production precision. Typed-only test targets are recomputed rather than reused as parser facts, preventing edge multiplication across unchanged precise builds.Low-memory mode changes execution policy, not analysis meaning. It uses aggressive GC, releases completed production type/SSA state before typed-test loading, and honors an optional soft Go runtime memory target. The target is neither an RSS ceiling nor a guarantee that all repositories can complete within that amount; Gograph reports fallback/failure normally rather than silently omitting precise facts.
A precise interface invocation whose SSA receiver is proven to contain one concrete dynamic type is devirtualized to one exact ordinary call. Otherwise it is represented by one call edge per valid named in-repository CHA target. A single visible implementation is never treated as proof.
callers Interface.Method(including inherited and promoted methods) expands through recorded implementers and deduplicates shared source expressions. Compiler-generated promoted-method forwarding remains traversal-only.Open CHA dispatch is conservative rather than points-to precise: it may retain implementations that cannot occur in one runtime configuration. Reflection,
unsafe, plugins, unresolved function values, test-only implementations, unnamed concrete types, and module-external implementations can still be incomplete. Precise test attribution also proves single-assignment, non-escaping concrete interface locals; other interface targets remain explicitly possible, andtyped_partialmeans some tests stayed on parser heuristics.Callback references are retained only when they resolve to repository callables, and exact call edges are deduplicated before serialization.
Mutation queries ignore ordinary local assignments and retain owning type information when statically known, so
Type.Fielddisambiguates same-named fields.Synchronization extraction requires a receiver tied to a known
synctype. Error messages come frompanic,errors.New, andfmt.Errorf, including import aliases.Heuristic extractors (routes, SQL, parser-only tests, and error mapping) are navigation aids, not authoritative program analysis. SQL classification is limited to static PostgreSQL literals, reports
exact/partial/unknown, resolves CTEs to their terminal operation, preserves data-modifying CTE write evidence, and does not claim coverage of runtime-generated SQL. Typed test attribution is still static evidence rather than runtime coverage proof.Security flow analysis is interprocedural and path-insensitive, with call/return context for the 3 most recent call sites by default (context depth up to 16; deeper returns that lose their call site are kept at low confidence), bounded by a size-derived work budget that reports incomplete runs explicitly. Default graphs resolve direct local/imported functions;
build . --precisesupplies stronger method/interface targets. It does not model reflection, globals, arbitrary heap aliases, or every dynamic call. Unresolved external transformations are retained with low confidence; every finding requires source review.
No multi-language parsing
No AI/model API calls
No embeddings or SaaS backend
No remote telemetry or hosted analytics (optional audit sessions write local metadata only)
No replacement for compiler/type-checker correctness
Contributing
Pull requests welcome! See CONTRIBUTING.md for build, test, and contribution guidelines.
Language Support:
gographcurrently 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.
Available Tools
70 toolsgograph_apiARead-onlyIdempotent
Detect public API surface drift by comparing exported Go symbols between the current working tree and a baseline. A since value ending in .json loads a regular saved graph inside the project root with no linked path component and the exact current repository source-policy marker; its serialized root is ignored. Otherwise gograph validates the value as a Git ref and uses git archive to build a temporary baseline. Read-only apart from reading the selected graph or extracting a temporary archive that is removed after the call. WHEN TO USE: Before releasing or merging a PR to catch breaking-change regressions — exported symbols added, removed, or renamed since the baseline. NOT TO USE: For listing current exports without a diff baseline (use gograph_public or gograph_skeleton instead). RETURNS: JSON with baseline and breaking flags; nested exported_symbols, interfaces, structs, and routes groups containing added/removed arrays plus changed detail objects; affected_tests, affected_mocks, and findings arrays. Empty groups indicate no drift.
Inputs: since (required), root, intention, session_id.
gograph_arityARead-onlyIdempotent
Find functions and methods with at least a threshold number of parameters — the long-parameter-list smell. min sets the inclusive minimum (default: 5; 0 includes zero-arity functions), matching CLI --min. WHEN TO USE: During code smell audits. NOT TO USE: For struct field counts (use gograph_fields or gograph_godobj). RETURNS: Functions meeting the threshold with parameter count, signature, and file location.
Inputs: min, root, intention, session_id.
gograph_boundariesARead-onlyIdempotent
Refresh source analysis and check package imports against a boundaries.json configuration. The required config defaults to the committable gograph/boundaries.json, then .gograph/boundaries.json; explicit paths must remain inside the analyzed project, and every path component plus the final regular file is read through the rooted repository boundary. Create it with gograph_boundaries_create. WHEN TO USE: In CI gates or post-edit reviews to enforce layer separation. NOT TO USE: For unconstrained dependency exploration (use gograph_deps or gograph_coupling). RETURNS: Structured pass state and boundary violations.
Inputs: root, limit, config, cursor, +2 more.
gograph_boundaries_createA
Create a baseline architecture boundary configuration from the repository's current package imports. Defaults to the committable gograph/boundaries.json under the graph root, uses repository-rooted regular-file creation, and refuses linked paths or overwrite. Mutating and non-idempotent; no network access. WHEN TO USE: Once when adopting boundary checks in an existing repository, then review and tighten the generated rules. NOT TO USE: To verify an existing configuration (use gograph_boundaries). RETURNS: The written config path or an error when the path is unsafe or already exists.
Inputs: root, config, intention, session_id.
gograph_calleesARead-onlyIdempotent
Find functions and methods called by the specified function. Defaults to one-hop fan-out; depth 2-10 expands the downstream call graph. WHEN TO USE: To understand a function's downstream dependencies. NOT TO USE: For upstream callers (use gograph_callers); for package dependency trees (use gograph_deps). RETURNS: Callee symbols with package paths, file locations, and call-site line numbers; with mermaid=true, Mermaid flowchart text.
Inputs: function (required), root, depth, limit, +5 more.
gograph_callersARead-onlyIdempotent
Find functions and methods that call the specified function or interface method. Defaults to one-hop fan-in; depth 2-10 expands callers-of-callers. In a precise graph, Interface.Method expands through all recorded implementations and reports a shared source call site once. WHEN TO USE: Before renaming, removing, or changing a function or interface method signature. NOT TO USE: For unbounded upstream blast radius (use gograph_impact); for downstream callees (use gograph_callees). RETURNS: Caller symbols with package paths, file locations, and call-site line numbers; with mermaid=true, Mermaid flowchart text.
Inputs: function (required), root, depth, exact, +6 more.
gograph_capabilitiesARead-onlyIdempotent
List the running gograph server version, all available MCP tool names, and recommended agent workflows. Once the project-scoped MCP server has started, this tool has no additional graph-state prerequisite. WHEN TO USE: Call once per session to record the analysis instrument and orient before issuing analytical queries. NOT TO USE: Do not repeat after capabilities are cached in context. RETURNS: JSON with version, every registered tool name, recommended workflow sequences, and known static-analysis limitations; tool descriptions are in tools/list.
Inputs: root, intention, session_id.
gograph_changesARead-onlyIdempotent
Compare Go declaration fingerprints, including bodies, without marking every symbol in an edited file modified. Without git_ref, inspects trusted persisted graph.json without refreshing, or the startup fallback if no usable artifact exists. With git_ref, refreshes and extracts a confined declaration baseline without compiling application code. Existing but deselected files are excluded, not deleted; unsafe inputs and parse failures produce diagnostics, never deletion proof. Missing legacy declaration fingerprints produce unknown. Read-only analysis. WHEN TO USE: After editing to identify changed declarations before impact/review. NOT TO USE: For line-level diffs or a complete census when evaluation is partial/cannot_evaluate. RETURNS: Native gograph.changes.v1 with complete/partial/cannot_evaluate, diagnostics, changed_files, and new/modified/deleted/excluded/unknown symbol rows; CLI uses the same value and exits 2 for incomplete evaluation.
Inputs: root, git_ref, intention, session_id.
gograph_checkARead-onlyIdempotent
Refresh source analysis and run static policy checks: boundaries, API drift, changed-route/export tests, test coverage, orphans, globals, arity, and complexity. The default or a relative checks config is confined to a regular non-linked file beneath the project; an absolute config is an explicit operator-selected regular file. Baselines use the same validated builder as CLI: a value ending in .json loads a regular saved graph inside the project root with no linked component and the exact current source-policy marker, ignoring its serialized root; otherwise it is treated as a Git ref and extracted temporarily. WHEN TO USE: During PR review or pre-commit analysis. NOT TO USE: For CI process exit enforcement (use CLI gograph gate). RETURNS: Structured pass/warn/fail status, findings, and summary counts.
Inputs: root, since, config, intention, +2 more.
gograph_complexityARead-onlyIdempotent
Report estimated cyclomatic complexity for Go functions, sorted highest-to-lowest with severity labels (LOW/MEDIUM/HIGH/VERY HIGH). A function whose repository source cannot be read or parsed safely is retained as UNKNOWN with score -1. Optional symbol substring filters to a specific function or set of functions; top limits the report (default: 20; 0 = all). WHEN TO USE: During code quality audits, identifying functions that need decomposition, or setting complexity budgets in CI. NOT TO USE: For import dependency metrics (use gograph_coupling or gograph_deps); for God Object detection (use gograph_godobj). RETURNS: Structured list of functions with complexity score and severity label; empty when no functions match the filter.
Inputs: top, path, root, symbol, +3 more.
gograph_concurrencyARead-onlyIdempotent
Find indexed concurrency sites in the codebase: goroutine spawns (go statements), channel sends, and calls on sync.Mutex/RWMutex, sync.WaitGroup, and sync.Once. Optional term filter (e.g., "mutex", "goroutine", "channel"). WHEN TO USE: When auditing race safety, understanding async flow, or locating synchronization points before a concurrency refactor. NOT TO USE: For standard sequential call flow analysis (use gograph_callers/gograph_callees). RETURNS: File locations, line numbers, and primitive kind for each indexed concurrency site; empty when no sites are found. Channel receives and select statements are not indexed.
Inputs: root, term, limit, cursor, +2 more.
gograph_constructorsARead-onlyIdempotent
Find all factory and constructor functions that instantiate and return a named Go struct (functions whose return type includes the struct name). WHEN TO USE: When looking for the canonical way to create a struct, or before modifying struct initialization to ensure all construction paths are updated. NOT TO USE: For direct composite-literal sites (use gograph_literals); for struct fields (use gograph_fields). RETURNS: List of constructor function names with signatures, package paths, and file locations; empty when no factory functions are found.
Inputs: struct (required), root, limit, cursor, +2 more.
gograph_contextARead-onlyIdempotent
Fetch a pre-flight context bundle for a single Go symbol: AST node metadata, source code, direct callers, direct callees, linked test functions, and architectural role classification — all in one call. Read-only analysis; an active audit session may append local command telemetry. Set uncommitted=true to bundle context for all currently modified symbols at once. WHEN TO USE: As the first call before editing a symbol — eliminates 4–5 separate tool roundtrips. NOT TO USE: For package-level orientation (use gograph_focus); for transitive blast radius (use gograph_impact). RETURNS: JSON with node (first match), nodes[] (all matches), source, callers[], callees[], tests[], test_results[], and top-level role; a missing symbol is a named error. source_error reports a partial context when indexed metadata exists but source cannot be served, also named in _meta.gograph_graph_state.read_diagnostic. With uncommitted=true, returns a contexts[] array; count:0 when no uncommitted symbols exist.
Inputs: root, exact, symbol, intention, +2 more.
gograph_couplingARead-onlyIdempotent
Report fan-in (Ca), fan-out (Ce), and instability I=Ce/(Ca+Ce) per package. package filters by substring; include_stdlib and internal_only control scope. WHEN TO USE: To evaluate package isolation. RETURNS: Package coupling records; with mermaid=true, Mermaid flowchart text.
Inputs: root, mermaid, package, intention, +3 more.
gograph_coverageARead-onlyIdempotent
Return the transitive set of production functions and methods statically reachable from one test function. Exact results have an all-static path; any parser-only or CHA dispatch edge degrades that symbol and its descendants to possible. Same-named tests in multiple packages return status=ambiguous and are never merged; retry with the stable test ID from matched_tests or gograph_identity. The optional package qualifier resolves the uncommon in-package versus external foo_test ID collision. Set exact_only=true to omit possible results. This is static attribution, not runtime or branch coverage proof. WHEN TO USE: To map one test to the product symbols it structurally exercises. NOT TO USE: To claim execution or branch coverage. RETURNS: gograph.coverage.v1 JSON with analysis precision, test-call resolution, matched tests, symbols, resolution, depth, representative stable-ID paths, and limitations.
Inputs: test (required), root, package, intention, +2 more.
gograph_dependentsARead-onlyIdempotent
Find all packages that import the named package (inverse of gograph_deps). WHEN TO USE: Before a package-level interface change or removal. NOT TO USE: For a single function's callers (use gograph_callers). RETURNS: Dependent packages; with mermaid=true, Mermaid flowchart text.
Inputs: package (required), root, limit, cursor, +3 more.
gograph_depsARead-onlyIdempotent
List the import dependencies of a named package. With transitive=false (default), returns direct imports; true returns the BFS closure. WHEN TO USE: When auditing package layering. NOT TO USE: For reverse lookup (use gograph_dependents). RETURNS: direct[] and transitive[] arrays; with mermaid=true, Mermaid flowchart text; found:false when absent.
Inputs: package (required), root, mermaid, intention, +2 more.
gograph_diagramARead-onlyIdempotent
Refresh source analysis and generate a Mermaid architecture diagram of the package dependency graph. WHEN TO USE: Onboarding, architecture review, or communicating package structure. Use group_by=module for monorepos and group_by=file for drill-downs. NOT TO USE: For call-graph traversal or single-package focus. RETURNS: Mermaid text; use max_depth or coarser grouping for large graphs.
Inputs: root, group_by, intention, max_depth, +2 more.
gograph_docARead-onlyIdempotent
Fetch Go documentation for a package, stdlib symbol, or third-party symbol by running go doc <query>. The handler does not query the graph, though the project-scoped MCP server must already have started with a usable artifact or buildable Go source. Filesystem-shaped queries are rejected, and the command is refused for source-tree links the Go toolchain may inspect across the selected root plus its effective module root, or the workspace root and member trees; .git and .gograph are excluded from that preflight. It also refuses a special recognized Go build input, linked/non-regular Go tool metadata (go.mod, go.sum, go.work, go.work.sum, or vendor/modules.txt), or a workspace member outside the workspace directory. Each applicable member directory, go.mod, and optional go.sum is validated first. Dependency and toolchain resolution remain open-world under the user's Go environment. WHEN TO USE: When a call chain reaches code outside the project. NOT TO USE: For project-internal symbols (use gograph_source or gograph_context). RETURNS: A one-element JSON array containing {query, output}, where output is the raw go doc text; an error when the query or repository input is unsafe, the symbol is not found, or go is unavailable.
Inputs: query (required), root, intention, session_id.
gograph_embedsARead-onlyIdempotent
Find all Go structs that embed the named struct via anonymous field composition. WHEN TO USE: When understanding how a base type is extended throughout the codebase, or before modifying a shared embedded struct to estimate blast radius. NOT TO USE: For interface implementations (use gograph_implementers); for named field type references in other structs (use gograph_usages). RETURNS: List of embedding parent struct names with package paths and file locations; empty when the struct is embedded nowhere.
Inputs: struct (required), root, limit, cursor, +2 more.
gograph_endpointARead-onlyIdempotent
Build a full vertical slice for one HTTP route: the matched handler symbol, a BFS call chain downstream (default depth 5), all SQL queries emitted in that chain, and all env vars read. Constant nested Gin/Echo/Fiber Group prefixes and Chi Route closure prefixes are composed into final paths; dynamically computed prefixes remain unresolved and can still be queried by suffix or handler. WHEN TO USE: When auditing what an API endpoint does end-to-end — its downstream dependencies, database queries, and configuration reads. NOT TO USE: For listing all routes (use gograph_routes first to find the pattern); for raw handler source code only (use gograph_source). RETURNS: Array of endpoint slices with route, handler, call chain, SQL, and env fields; found:false with a suggestion when the query does not match any route. query accepts route pattern ("POST /api/users"), path fragment ("/users"), or handler name. depth controls call-chain BFS depth (default: 5).
Inputs: query (required), root, depth, mermaid, +3 more.
gograph_envsARead-onlyIdempotent
Find all environment variable reads in the codebase via os.Getenv, os.LookupEnv, and common config frameworks, with their enclosing function context. Optional term filters by key name substring (e.g., "DATABASE" matches DATABASE_URL and DATABASE_HOST). WHEN TO USE: When compiling a deployment configuration manifest, documenting required env vars, or auditing what secrets a service reads at startup. NOT TO USE: For reading actual runtime env values (this is static analysis); for database queries (use gograph_sql). RETURNS: List of env key names, calling function, and file/line; empty when no env reads match the filter.
Inputs: root, term, limit, cursor, +2 more.
gograph_errorflowARead-onlyIdempotent
Trace how a named error sentinel or error message string is defined, returned, and propagates up the call graph toward HTTP handlers or CLI entry points. Accepts either query (preferred) or term as the error name or message substring. WHEN TO USE: When auditing how a specific error is produced and handled end-to-end — find definition sites, all return sites, and upstream propagation paths (e.g., ErrNotFound). NOT TO USE: For general upstream traversal of any function (use gograph_callers or gograph_impact); for listing all error definitions (use gograph_errors). RETURNS: Definition sites, return sites, propagation path chains, and related test names; paths is empty when no propagation chain is found. Note: heuristic analysis — does not perform SSA or full data-flow tracking.
Inputs: root, term, query, no_tests, +2 more.
gograph_errorsARead-onlyIdempotent
Find all error and panic sites in the codebase: errors.New, fmt.Errorf, sentinel var declarations, and panic calls. Optional term filters by message substring (e.g., "ErrInvalid", "unauthorized"). WHEN TO USE: When cataloging error codes and panic paths, standardizing error messages, or checking whether a specific error string is already defined before adding a new one. NOT TO USE: For tracing how an error propagates up the call stack (use gograph_errorflow instead). RETURNS: List of error or panic sites with message text, file path, and line number; empty when no matches found.
Inputs: root, term, limit, cursor, +3 more.
gograph_explainARead-onlyIdempotent
Generate a synthesized, LLM-ready narrative for a Go symbol: role classification, callers, callees, complexity, SQL, env vars, HTTP routes, concurrency primitives, tests, and interface satisfaction — all in one structured document. WHEN TO USE: For onboarding to an unfamiliar symbol, generating PR documentation, or getting an opinionated architectural assessment without issuing multiple tool calls. NOT TO USE: For raw source code (use gograph_source); for targeted blast-radius analysis (use gograph_impact). RETURNS: Rich structured JSON with role, narrative summary, and all associated cross-references; {"found":false} when symbol is not in the graph.
Inputs: symbol (required), root, intention, session_id.
gograph_exploreARead-onlyIdempotent
Explore a lexical term or Go symbol in one bounded call. Standard mode combines ranked matches with selected-symbol source, direct callers/callees, tests, and exact impact. compact=true returns discovery, selected-node metadata, role, complete counts, and explicit omitted_sections while suppressing token-heavy bodies (default limit 5). deep=true retains standard evidence and adds bounded depth-3 exact identity callers/callees, package context, and explanation (default limit 25). compact and deep are mutually exclusive; an explicit limit overrides their defaults. Possible dispatch is excluded from bundled identity impact and deep traversals. Question-like text is lexical, not model-interpreted. Focused tools remain authoritative for complete output. RETURNS: shared gograph.explore.v1 with mode, selection_basis, ambiguity, totals, truncation, and omission metadata.
Inputs: query (required), deep, root, exact, +4 more.
gograph_fieldsARead-onlyIdempotent
Extract all declared fields from a named Go struct: field names, Go types, and raw struct tag strings (json, db, yaml, gorm, etc.). WHEN TO USE: When mapping JSON/DB serialization tags, inspecting struct layouts, or enumerating fields before adding a new one. NOT TO USE: For methods on the struct (use gograph_node or gograph_source); for all struct initialization sites (use gograph_literals). RETURNS: Array of field entries with name, type, and tag string; empty when the struct is not found.
Inputs: struct (required), root, limit, cursor, +2 more.
gograph_fixturesARead-onlyIdempotent
Find test helper structs and factory/builder functions declared in *_test.go files for a named package. WHEN TO USE: Before writing new tests — check what test infrastructure (helper builders, stub factories, shared setup structs) already exists in the package to avoid duplication. NOT TO USE: For test functions that exercise a symbol (use gograph_tests); for external test data files on disk (those are not tracked in the graph — use filesystem search). RETURNS: Symbols defined in test files for the package including helper structs and factory functions; empty when the package has no test helper infrastructure.
Inputs: package (required), root, limit, cursor, +2 more.
gograph_flowARead-onlyIdempotent
Find potential untrusted-data paths from HTTP request objects, decoded JSON values, or environment variables to SQL query text, process execution arguments, filesystem paths, or outbound HTTP targets. Run gograph build . --precise first for stronger method/interface targets. WHEN TO USE: During a security review or before changing request parsing, command execution, file access, SQL construction, or URL handling. NOT TO USE: As proof of exploitability; the analysis is path-insensitive and call/return context for the 3 most recent call sites by default (context depth up to 16; deeper returns that lose their call site are kept at low confidence), bounded by a size-derived work budget that reports incomplete runs explicitly. RETURNS: Structured findings with source, sink, severity, confidence, parameter_only (constant non-shell program), and path steps; an exhausted budget lists top_functions by work. The policy (.gograph/flow.json or config) adds return-value or argument sanitizers and custom sources and sinks by function.
Inputs: root, sink, term, config, +7 more.
gograph_focusARead-onlyIdempotent
Extract a comprehensive structural summary of one Go package: all files, defined symbols, internal call edges, and package-level imports. WHEN TO USE: When orienting to an unfamiliar package before editing it — provides a full map of what the package contains and how it connects to the rest of the codebase. NOT TO USE: For a single symbol's details (use gograph_context or gograph_source); for global keyword searches (use gograph_query). RETURNS: All files, symbol names, call edges, and import paths within the package; empty when the package is not found.
Inputs: package (required), root, limit, cursor, +2 more.
gograph_globalsARead-onlyIdempotent
Find package-level variable declarations (var blocks) and the functions that mutate them in a specific package. WHEN TO USE: When auditing mutable global state, identifying thread-safety hazards, or locating shared singleton variables before a concurrency refactor. NOT TO USE: For local-scope variables; for environment variable reads (use gograph_envs). RETURNS: Package-level variable names, types, and the functions that write to them; empty when the package has no package-level variables.
Inputs: package (required), root, limit, cursor, +2 more.
gograph_godobjARead-onlyIdempotent
Detect God Object anti-pattern candidates by scoring structs on method count, field count, and outgoing call count. Thresholds: methods (default: 5), fields (default: 8), calls (default: 15); top limits results (default: 10). Exceeding any enabled threshold qualifies a struct, and the combined excess determines rank. WHEN TO USE: During architecture reviews to find monolithic structs that should be decomposed. NOT TO USE: For general struct layout inspection (use gograph_fields); for single-function complexity (use gograph_complexity). RETURNS: Ranked candidates with method, field, and call counts; empty when no threshold is exceeded.
Inputs: top, root, calls, fields, +3 more.
gograph_hotspotARead-onlyIdempotent
Rank functions by incoming call count (fan-in) to identify the most-depended-on symbols in the codebase. top controls result count (default: 10; 0 = all). Set include_tests=true to count test-file call edges — by default excluded so test helpers don't dominate rankings in test-heavy codebases. WHEN TO USE: When deciding where to invest refactoring effort or documentation — high fan-in functions are the highest-risk change targets. NOT TO USE: For single-package metrics (use gograph_focus or gograph_coupling); for complexity scores (use gograph_complexity). RETURNS: Ranked list of function names with fan-in count and package location.
Inputs: top, root, intention, session_id, +1 more.
gograph_httpcallsARead-onlyIdempotent
List a bounded page of HTTP evidence from imported, unshadowed net/http Get/Post/PostForm/Head calls and possible NewRequest/NewRequestWithContext construction. Client receiver methods and arbitrary URL-building functions are not inferred. Static strings and bounded lexical base + static suffix expressions are recorded; runtime environment values are never read. Construction is not dispatch proof. Workspace http_clients may explicitly map bases or env:KEY to scoped logical authorities; unresolved destinations remain workspace diagnostics. Optional term matches method, URL/base, or function. RETURNS: gograph.results.v1 rows with file/line and dynamic base/suffix or request-only evidence in detail, plus total/returned/truncated/next_cursor. For server routes use gograph_routes.
Inputs: root, term, limit, cursor, +2 more.
gograph_identityARead-onlyIdempotent
Resolve an exact Go symbol spelling or canonical stable ID to location-independent symbol identity plus current source location. Canonical IDs are module import path + receiver/name and survive line shifts and file moves within the same package; package/module moves, receiver changes, and renames change the ID. Ambiguous short names return every candidate and never select one silently. An optional exact package qualifier disambiguates the uncommon in-package versus external foo_test ID collision. WHEN TO USE: Before persisting cross-document references or to re-resolve an existing stable ID. RETURNS: gograph.identity.v1 JSON with status exact, ambiguous, or not_found and deterministic matches.
Inputs: symbol (required), root, package, intention, +1 more.
gograph_impactARead-onlyIdempotent
Traverse the call graph backwards to find every symbol that transitively calls the target — the full upstream blast radius of a change. Three modes: (1) single symbol via symbol; (2) uncommitted changes via uncommitted=true; (3) git-ref changes via since. WHEN TO USE: Before refactoring a core function to see what breaks. NOT TO USE: For direct one-hop callers only (use gograph_callers). RETURNS: Transitive upstream affected symbols; with mermaid=true, Mermaid flowchart text; a bounded native page (including empty pages). Exact and possible paths remain distinct; Mermaid uses dotted edges for possible evidence.
Inputs: root, limit, since, cursor, +6 more.
gograph_implementersARead-onlyIdempotent
Find all concrete structs that implement a named Go interface. Type-checked production results are merged with AST-discovered implementations from test files because production package loading excludes test variants. Type-checked production results merge AST-discovered test-file fakes; set test_only=true to restrict to structs in *_test.go files (mocks/stubs). WHEN TO USE: When tracing polymorphism, locating dependency injection points, or finding all mock implementations of an interface. NOT TO USE: For interfaces a struct satisfies — inverse direction (use gograph_interfaces instead); for struct fields (use gograph_fields). RETURNS: List of implementing struct names with package paths and file locations; empty when no struct implements the interface.
Inputs: interface (required), root, limit, cursor, +3 more.
gograph_importsARead-onlyIdempotent
Find all files and packages in the codebase that import a specific package by its exact import path. WHEN TO USE: When isolating usage of a third-party library before removing or replacing it, or tracing where an internal package is consumed from outside. NOT TO USE: For a package's own outgoing imports (use gograph_deps); for reverse package-level dependency lookup by short name (use gograph_dependents). RETURNS: File paths and package names of all importers; empty when the package is imported nowhere.
Inputs: package (required), root, limit, cursor, +2 more.
gograph_interfacesARead-onlyIdempotent
Find all Go interfaces satisfied by a named concrete struct (duck-typing resolution — inverse of gograph_implementers). Given a struct name, returns every interface whose complete method set is a subset of that struct's methods. WHEN TO USE: When you need to know which contracts a struct implicitly fulfills — useful before refactoring a method to understand which interface contracts will break. NOT TO USE: For finding structs that implement an interface (use gograph_implementers); for listing interface declarations in a package (use gograph_node or gograph_public). RETURNS: Interface names, method signatures, and file locations; empty when the struct satisfies no known interfaces.
Inputs: struct (required), root, limit, cursor, +2 more.
gograph_literalsARead-onlyIdempotent
Find every composite-literal initialization site for a named Go struct — all locations where Foo{...} syntax is used to construct the struct. WHEN TO USE: Before adding a required field to a struct — every site returned will fail to compile if the new field has no default; run this first to scope the migration blast radius. NOT TO USE: For finding string or integer magic values (use gograph_envs or grep for those); for factory functions that return the struct (use gograph_constructors). RETURNS: All file paths and line numbers where the named struct is composite-initialized; empty when the struct has no direct initialization sites.
Inputs: struct (required), root, limit, cursor, +2 more.
gograph_mocksARead-onlyIdempotent
Find structs in *_test.go files that implement a named interface — test doubles, mocks, and stubs. Equivalent to gograph_implementers with test_only=true; kept for compatibility. WHEN TO USE: When writing tests and wanting to find existing mock implementations before creating a new one. NOT TO USE: For production interface implementers (use gograph_implementers without test_only); prefer gograph_implementers(test_only=true) for new code. RETURNS: Test-file struct names implementing the interface with file locations; empty when no test mocks exist for the interface.
Inputs: interface (required), root, limit, cursor, +2 more.
gograph_mutateARead-onlyIdempotent
Find struct-field and package-global mutation sites. Use Type.Field to exclude same-named fields on unrelated types; ordinary local-variable assignments are excluded. A precise graph adds ++/+=, pointer-alias, atomic/sync/wrapper, and channel mutations and re-runs that analysis after source edits. WHEN TO USE: Diagnosing state changes or auditing mutability. NOT TO USE: For field declarations (gograph_fields) or whole-struct initialization (gograph_literals). RETURNS: Mutation locations and indirect mutator method names when applicable.
Inputs: field (required), root, limit, cursor, +2 more.
gograph_nodeARead-onlyIdempotent
Fetch AST metadata for a named symbol, package, or file: kind, file path, line number, full signature, doc comment, and struct fields if applicable. WHEN TO USE: When you need structural metadata (kind, signature, line number) without the full source body — lighter than gograph_source for metadata-only lookups. NOT TO USE: For full source code (use gograph_source); for call relationships (use gograph_callers/gograph_callees). RETURNS: Node properties array with kind, file, line, and signature; empty when the name is not found.
Inputs: name (required), root, limit, cursor, +2 more.
gograph_orphansARead-onlyIdempotent
Find functions and methods unreachable from runtime roots (main/init), test/benchmark/fuzz roots, HTTP route handlers, and eligible externally callable exports; exports confined under internal/ are not roots. Uses full BFS reachability. WHEN TO USE: During code cleanup or dead-code audits. NOT TO USE: For checking one symbol's usages (use gograph_usages or gograph_callers). RETURNS: Orphan symbols with package paths and file locations; empty means no unreachable code was detected.
Inputs: root, limit, cursor, intention, +1 more.
gograph_pathARead-onlyIdempotent
Find the best call chain from one symbol to another. Competing paths rank exact before possible, then shorter, production before tests, typed resolution before heuristics, with a deterministic canonical tie-breaker. WHEN TO USE: To confirm reachability between non-adjacent symbols. NOT TO USE: For all transitive upstream callers (use gograph_impact). RETURNS: from, to, found, and steps[]; with mermaid=true, Mermaid flowchart text.
Inputs: to (required), from (required), root, mermaid, +2 more.
gograph_planARead-onlyIdempotent
Generate a structured pre-edit plan for a target symbol: which symbols to read first, which tests cover them, which routes and env vars they touch, and whether the change is public-API or SQL-touching. Set with_context=true to inline full source+callers+callees for each symbol to inspect — eliminates follow-up gograph_context calls. WHEN TO USE: Before multi-file refactoring or architectural changes to understand scope upfront. NOT TO USE: For trivial single-line fixes; for post-edit verification (use gograph_review instead). RETURNS: JSON with inspect_first[], tests[], routes[], env[], and a risk object (public_api, touches_sql, etc.); with with_context=true, also includes inspect_contexts[] with full per-symbol bundles.
Inputs: root, symbol, intention, session_id, +2 more.
gograph_publicARead-onlyIdempotent
List all exported (public) symbols of a specific package, including functions, methods, types/interfaces, variables, and constants. WHEN TO USE: When reviewing a package's public contract before changing it, building integration documentation, or checking what a package exposes to callers. NOT TO USE: For unexported/private symbols (use gograph_node or gograph_focus); for API drift detection against a baseline (use gograph_api). RETURNS: List of exported symbol names with kinds and file locations; empty when the package has no exports or is not found.
Inputs: package (required), root, limit, cursor, +2 more.
gograph_queryARead-onlyIdempotent
Search the graph index for symbols, packages, files, and import edges that match one or more keyword substrings. Multiple terms use OR semantics, matching CLI query term.... WHEN TO USE: During initial exploration when you have a keyword or feature name but do not know its package. NOT TO USE: When you already know the exact symbol (use gograph_source or gograph_node); for package dependency trees (use gograph_deps). RETURNS: Matching symbols, files, and imports; empty when no terms match.
Inputs: root, term, limit, query, +5 more.
gograph_returnusageARead-onlyIdempotent
Show how each caller uses the return value(s) of a named function: discarded, assigned, partially ignored, returned upstream, or passed directly to another call. WHEN TO USE: Before changing a function's return signature — see which callers ignore the error or only use some return values. NOT TO USE: For error propagation tracing (use gograph_errorflow); for finding all callers without usage detail (use gograph_callers). RETURNS: List of call sites with usage classification (discarded/assigned/partially_ignored/returned/passed); empty when the function has no callers.
Inputs: function (required), root, limit, cursor, +2 more.
gograph_reviewARead-onlyIdempotent
Summarize the scope and risk profile of a change: which symbols changed, which tests cover them, which routes and env vars they touch, and whether SQL is involved. Requires either symbol or uncommitted=true. WHEN TO USE: After editing — as a post-edit verification step before committing; confirms the blast radius matches expectations. Use uncommitted=true to review all current unstaged changes at once. NOT TO USE: For boundary constraint enforcement (use gograph_boundaries); for pre-edit planning (use gograph_plan). RETURNS: JSON with changed_symbols[], tests[], routes[], env[], errors[], and a risk object (public_api, touches_sql, touches_routes, touches_env).
Inputs: root, symbol, intention, session_id, +1 more.
gograph_riskARead-onlyIdempotent
Evaluate the change risk profile of target symbol(s) or uncommitted changes. Combines blast radius, cyclomatic complexity, test coverage, and downstream environment/SQL dependencies into a normalized 0–100 risk score and verdict. Requires either symbol or uncommitted=true. WHEN TO USE: Before committing edits or when planning changes to understand the technical risk. NOT TO USE: For post-edit review checklist generation (use gograph_review); for pre-edit plan generation (use gograph_plan). RETURNS: JSON with title, results[] containing risk scores, verdicts, and breakdown metrics, and optional message.
Inputs: root, symbol, intention, session_id, +1 more.
gograph_routesARead-onlyIdempotent
List a deterministic bounded page of HTTP routes with methods, URL patterns, handler names, and source locations. Production routes are returned by default; include_tests=true adds *_test.go registrations. Optional term matches method/path, handler, or file. module selects an exact module path/directory, a unique nested-module directory basename, or the repository directory name for a root module. limit defaults to 100 and is restricted to 1-200; next_cursor continues the same filtered census. Each page is also bounded to 64 KiB so the result stays directly consumable instead of spilling to an out-of-band file. Constant nested Gin/Echo/Fiber Group prefixes and Chi Route closure prefixes are composed; Gin/Fiber use the final variadic argument as the terminal handler, while Echo uses the handler immediately after the path. Dynamically computed prefixes remain unresolved. WHEN TO USE: To inventory one service/module or find a route before gograph_endpoint. NOT TO USE: For a handler's downstream call chain (use gograph_endpoint). RETURNS: gograph.routes.v1 JSON with total, returned, truncated, routes[], and next_cursor when more matches exist.
Inputs: root, term, limit, query, +5 more.
gograph_schemaARead-onlyIdempotent
Find Go structs that declare a mapping to a specific database table via struct tags (e.g., db:"table_name", gorm:"table:table_name"). WHEN TO USE: When tracing which Go types represent a database table, or before writing a migration to understand the current ORM model. NOT TO USE: For non-tagged Go structs used as query results (use gograph_fields or gograph_query instead). RETURNS: Matching struct names with package paths and file locations; empty when no structs map to the named table.
Inputs: table (required), root, limit, cursor, +2 more.
gograph_session_auditARead-onlyIdempotent
Review and grade agent compliance (Plan rule, Review rule, Composability/Efficiency) and tool success rates. Session IDs are strictly validated and only regular repository-confined logs are read. No additional prerequisite once the MCP server is running. WHEN TO USE: After ending a session to obtain compliance metrics and recommendations. RETURNS: Audited session details and grade.
Inputs: json, root, intention, session_id.
gograph_session_cleanupADestructiveIdempotent
Archive stale and inactive session telemetry without following linked repository paths; never deletes. Each pass moves files into .gograph/to_delete//. First ends other callers' CLI-owned sessions idle past the idle limit (GOGRAPH_SESSION_IDLE_LIMIT, default 2h) or MCP-owned sessions whose server process exited on this host (owners without metadata or on another host are kept), listing each, and archives an unselected legacy active_session.json; then archives logs with end records; preserves the selected active log and refuses while any other caller is still live. MCP annotations mark this operation mutating and destructive. No prerequisites. WHEN TO USE: Call after auditing to keep the repository clean. RETURNS: Each ended session, any archived legacy pointer, and the number of session logs moved with the archive folder, or Nothing to archive.
Inputs: root, intention, session_id.
gograph_session_createA
Start a telemetry audit session for tracking agent compliance and tool success metrics. Writes only regular, repository-confined session state under .gograph/sessions and refuses linked storage; MCP annotations mark it mutating and non-idempotent. No prerequisites once the MCP server is running. WHEN TO USE: Call once at the start of a multi-step coding task to track your work. Pass the returned ID as session_id on this caller's later requests. Independent callers may create alongside other active sessions. RETURNS: Message with the caller session ID.
Inputs: root, intention, session_id, custom_word.
gograph_session_endA
End only the explicitly selected caller session, append its end record, and remove its active marker through repository-confined regular-file operations. MCP annotations mark it mutating and non-idempotent. No additional prerequisite once the MCP server is running. WHEN TO USE: Call once after you have completed all edits and post-edit reviews. NOT TO USE: When no session is active. RETURNS: Message confirming ending of the session.
Inputs: root, intention, session_id.
gograph_skeletonARead-onlyIdempotent
Emit API signatures with function bodies stripped — struct definitions, interface declarations, and function/method signatures only. Supply file for one exact repository-relative indexed file; omit it for the full repository. Unknown files return an error. WARNING: whole-repository output can be very large. WHEN TO USE: For a file's declarations or a compact map of the entire codebase's shape. NOT TO USE: For full implementations (use gograph_source); for a single package (use gograph_public). RETURNS: Multi-line text of stripped declarations and package names.
Inputs: file, root, intention, session_id.
gograph_sourceARead-onlyIdempotent
Retrieve verbatim Go source for a named function, method, struct, interface, type, variable, or constant, including complete bodies or declarations. Source reads are confined to regular .go files beneath the analyzed repository and reject symlink path components. WHEN TO USE: When you need a specific implementation or declaration in full without loading a large file — a targeted alternative to reading the whole file. NOT TO USE: For call hierarchy information (use gograph_callers/gograph_callees); for AST metadata without the full source (use gograph_node). RETURNS: Raw Go source blocks with file paths and line numbers. The text carries the source or a named refusal: absent symbol, ambiguity with candidates, unsafe/unreadable source, invalid indexed range, or source exceeding 65536 bytes (with its size).
Inputs: symbol (required), root, intention, session_id.
gograph_sqlARead-onlyIdempotent
Return one bounded gograph.sql.v1 page of static PostgreSQL query literals with operation, read/write/DDL access, referenced tables, enclosing function, module ownership, and source location. Extraction covers direct literals plus statically resolvable local or same-file package const/var declarations, straight-line assignments, and bounded string concatenations. Filters in different categories AND-compose; repeated values within tables, verbs, and accesses OR-compose. Tests remain included by default for backward compatibility; set no_tests=true for production-only results. CTEs resolve to their actual operation, data-modifying CTEs retain write access/table evidence, PostgreSQL UPSERT remains INSERT, and unsupported classification is explicit rather than guessed. WHEN TO USE: Audit database interactions, write paths, or queries touching a table. NOT TO USE: For ORM struct mappings (use gograph_schema) or runtime-generated SQL that is not a static literal. RETURNS: A deterministic page with total/returned/truncated/next_cursor and queries[].
Inputs: root, term, limit, verbs, +8 more.
gograph_staleARead-onlyIdempotent
Check whether the trusted persisted graph index loaded from a regular, repository-confined .gograph/graph.json differs from the current selected-file inventory, effective Go build context, or selected source content digests. Modification times are returned only as diagnostics; legacy indexes without digests temporarily use the former mtime fallback until rebuilt. This tool intentionally does not refresh first; when the artifact is missing, unreadable, unsafe, or uses an unsupported source policy it compares against the startup auto-build fallback. WHEN TO USE: To decide whether CLI snapshot analysis or precise enrichment needs rebuilding. NOT TO USE: For module dependency freshness; for changed symbols (use gograph_changes). RETURNS: is_stale, graph_age, newest source metadata, changed_files, and build_context_changed.
Inputs: root, intention, session_id.
gograph_statsARead-onlyIdempotent
Report trusted persisted-index health and counts without refreshing source analysis, or startup-fallback health when graph.json is missing, unreadable, unsafe, or uses an unsupported source policy: schema/build timestamps, complete/partial status, ast/precise/precise_fallback analysis status, scanned/parsed/reused/rebuilt-package/failure counts, and graph entity totals. WHEN TO USE: To validate the snapshot/fallback before relying on its data. NOT TO USE: For a live symbol profile (use gograph_node or gograph_complexity). RETURNS: Structured build health and repository counts.
Inputs: root, intention, session_id.
gograph_stringsARead-onlyIdempotent
Search Go string literals in the indexed source files for one or more case-insensitive substrings (OR semantics), returning file, line, the literal, and its enclosing function. Route-shaped terms match any path-parameter spelling (:id, {id}, *id). Source is read through the confined repository reader; unreadable files are named in a warning. WHEN TO USE: To find raw route strings, URLs, SQL fragments, header names, or messages that are not symbols, instead of grep. NOT TO USE: For symbols (use gograph_query) or registered routes with handlers (use gograph_routes). RETURNS: gograph.results.v1 rows of kind string with total/returned/truncated/next_cursor.
Inputs: root, term, limit, query, +5 more.
gograph_summaryARead-onlyIdempotent
Single-call codebase briefing: top 3 hotspots (most-called symbols), worst instability package, highest cyclomatic complexity function, total orphan count, and god-object count. WHEN TO USE: At the very start of any session — replaces running gograph_hotspot + gograph_coupling + gograph_orphans + gograph_complexity + gograph_godobj separately (5 calls → 1). NOT TO USE: For detailed drill-down into a specific metric (use the dedicated tool after reviewing summary). RETURNS: JSON with symbols, packages, hotspots[], worst_instability, top_complexity, orphan_count, and god_object_count.
Inputs: root, intention, session_id.
gograph_testsARead-onlyIdempotent
Find test functions in *_test.go files that statically exercise a named symbol, or list all attributed test edges when no symbol is given. Direct mode accepts Receiver.Method (including pointer receivers) or a full stable symbol ID. By default this preserves the direct-edge result contract. Set transitive=true with a required symbol to return gograph.tests.v1 reverse attribution: a summary of every reaching test by depth and resolution, then one page (default 50, nearest first, with total, truncated and next_cursor) of tests with exact/possible resolution, depth, and a representative stable-ID path; max_depth keeps only nearby tests; exact_only omits uncertain paths and package disambiguates the selected product symbol. WHEN TO USE: To choose which tests to run after an edit (uncommitted=true); before editing a function — use transitive=true for router/callback-mediated coverage and direct mode for concrete test call sites. NOT TO USE: For test helper infrastructure (use gograph_fixtures); for running tests or proving runtime coverage. Set uncommitted=true, since=, or select=true with a symbol to get gograph.test_selection.v1: the tests to run for a change, grouped per package, each with an anchored go test -run pattern and ready go test commands (with the graph's build tags). RETURNS: Direct result rows by default, or a versioned reverse-transitive report or test selection when requested.
Inputs: root, limit, since, cursor, +9 more.
gograph_traceARead-onlyIdempotent
Alias for gograph_errorflow. Refreshes in-memory source analysis, then traces an error string heuristically from its definition up through the call chain to HTTP handlers. WHEN TO USE: Prefer gograph_errorflow; this alias exists for compatibility. RETURNS: The same structured output as gograph_errorflow.
Inputs: term (required), root, no_tests, intention, +1 more.
gograph_uncoveredARead-onlyIdempotent
Changed lines of non-test Go files that a go test -coverprofile run never executed, as exact line ranges per file (gograph.uncovered.v1). Lines outside coverage blocks are never reported; changed files without profile data are listed separately. WHEN TO USE: After running tests with -coverprofile, to see which lines of your change no test executed. RETURNS: files with uncovered ranges, changed and uncovered line counts.
Inputs: coverprofile (required), root, since, intention, +2 more.
gograph_untestedARead-onlyIdempotent
Sweep the full graph in one pass and return called production functions and methods without an exact transitive static path from any test. Precise direct calls and proof-backed concrete interface receivers are exact; open CHA or parser-only paths propagate possible to descendants, which remain visible with test_resolution=possible and possible_test_count. Repeatable CLI --exclude globs map to the MCP exclude string array and match repository-relative source paths lexically. This is static attribution, not runtime coverage proof. WHEN TO USE: During test census or pre-release hardening; it replaces N forward coverage or direct gograph_tests probes. NOT TO USE: For running tests or proving branch execution. RETURNS: JSON rows sorted by caller_count with stable_id, name, kind, file, line, caller_count, package, test_resolution, and optional possible_test_count.
Inputs: pkg, top, root, exclude, +4 more.
gograph_usagesARead-onlyIdempotent
Find every place a named Go type appears in function parameter lists, return type signatures, struct field or interface method declarations, and composite-literal construction. WHEN TO USE: Before changing an interface or type definition — see the consumption and construction blast radius. NOT TO USE: For call sites of a function (use gograph_callers); use gograph_literals when only struct Foo{...} initialization sites are needed; for all transitive callers use gograph_impact. Also answers struct fields: 'Type.Field', 'pkg.Type.Field', or a bare field name returns the declaration plus every field_read, field_write, field_address, and field_literal site, attributed to the declaring struct so promoted fields resolve; typed rows come from precise builds of production packages, while AST graphs return labelled name-only possible_field_use rows. RETURNS: File paths and line locations where the type or field appears; empty when the type is not referenced.
Inputs: type (required), root, limit, cursor, +2 more.
gograph_wikiADestructiveIdempotent
Generate the llm-wiki/ directory of machine-first markdown pages from the static graph. Pages produced: overview.md, architecture.md, hotspots.md, routes.md, env.md, errors.md, concurrency.md, api-surface.md, and one packages/.md per internal package. A relative output is anchored beneath the graph root and rejects linked components; an absolute output explicitly selects a local destination whose final directory must be real. Generated page paths and regular-file writes remain confined beneath the selected output root. Writes may overwrite existing regular files; MCP annotations mark it mutating and destructive. WHEN TO USE: At the start of an agent session on an unfamiliar codebase — run once to get a token-efficient orientation without issuing dozens of individual tool calls. NOT TO USE: For targeted symbol lookups (use gograph_context or gograph_source). RETURNS: JSON manifest of written page filenames and a count; error when the graph cannot be loaded or the output directory is unsafe or cannot be created.
Inputs: root, output, intention, session_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 70 tools
Descriptions do heavy lifting with explicit WHEN TO USE / NOT TO USE cross-references, which makes most pairwise choices resolvable. However, there is genuine redundancy: gograph_trace is an admitted alias of gograph_errorflow, gograph_mocks duplicates gograph_implementers(test_only=true), and a cluster of synthesis tools (gograph_summary, gograph_explain, gograph_explore, gograph_context, gograph_plan, gograph_review, gograph_risk, gograph_wiki) all promise 'bundled overview of a symbol/change' with only subtle deltas. An agent must read carefully to avoid picking the wrong bundle.
All 70 tools share the gograph_ prefix and snake_case, and most use a recognizable noun or verb form (gograph_callers, gograph_boundaries_create, gograph_session_end). A few are bare nouns where a verb would help (gograph_api, gograph_node, gograph_plan, gograph_risk, gograph_impact), and the mix of noun-style and verb-style names for sibling operations is a minor deviation but nothing inconsistent or chaotic.
70 tools is well past the point where a set stays legible; several are explicitly justified as call-count reducers (gograph_summary collapsing five metrics) or compatibility shims (gograph_trace, gograph_mocks), which signals the surface grew organically. The domain is legitimately broad (call graph, packages, HTTP, SQL, env, tests, sessions, wiki), but a single server with 70 entry points burdens tool selection.
Coverage of Go static analysis is unusually thorough: call graph both directions, package coupling, interface/inverse-interface, literals/constructors/usages, HTTP routes and endpoints, SQL, env vars, errors, concurrency, test attribution, complexity, boundaries, API drift, and session telemetry. Gaps are minor and mostly by design (no test execution, no symbol editing, runtime coverage only via external -coverprofile), which an agent can work around with the shell.
Maintenance
Related MCP Connectors
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that transforms codebases into knowledge graphs using Neo4J, enabling AI assistants to understand code structure, relationships, and metrics for more context-aware assistance.28MIT
- AlicenseNot gradedqualityBmaintenanceA local code-intelligence engine for AI agents that indexes repositories into a PostgreSQL-backed code graph and serves structured, token-budgeted context over MCP and HTTP, enabling targeted queries on symbols, dependencies, contracts, and impact analysis.7Apache 2.0
- AlicenseNot gradedqualityDmaintenanceZero-dependency Go MCP server that indexes codebases into an embedded Kùzu graph DB—enabling 90%+ token reduction, precise call-chain queries, and AI architectural health audits.1MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI coding agents to interrogate a local repository deterministically for symbols, dependencies, call paths, routes, tests, and Git impact, returning verified structured evidence with exact line citations instead of requiring the whole codebase to be read.261 PyPI4-