Gograph Go Repository Intelligence

gograph: Go Repository Intelligence

gograph is a local, AST-aware Go code intelligence engine that exposes 64 query, analysis, and workflow capabilities over the Model Context Protocol (68 endpoints including session lifecycle). It gives terminal LLMs (Claude Code, Cursor agents, OpenClaw) a structural view backed by a persisted or in-memory graph. gograph_explore offers compact, standard, and deep bounded discovery over one shared native result: compact preserves identity/role and complete counts, standard includes source/direct evidence and exact impact, and deep adds depth-3 exact evidence, package context, and explanation. gograph_context remains the focused known-symbol bundle. Actual savings depend on the task.

gopls provides live compiler-backed navigation, diagnostics, implementations, refactoring, and experimental MCP support. gograph complements it with a persisted repository graph, composed change-analysis workflows, and policy gates for coding agents.

When to invoke this skill

Activate whenever the user is working in a Go repository:

• Reading code, asking what a function does, or tracing a behavior across files.
• Planning, editing, refactoring, or deleting any Go symbol (function, method, struct, interface, package).
• Reviewing a Go diff or unstaged changes.
• Hunting a bug, auditing for security issues, or measuring complexity / coupling.

If a .go file is in the CWD or the user mentions a Go symbol, type, package, or interface by name, the skill applies.

Do NOT invoke for non-Go work. The skill is Go-scoped.

Prerequisite

For unrelated broken packages, use gograph build . --precise --strict --exclude-dirs=legacy,examples/broken. Pass the same --exclude-dirs to MCP startup and verify analysis_build_context.exclude_dirs in capabilities. Paths are literal root-relative subtrees; imported dependencies still must compile. Excluded code is outside the census. Workspace members use exclude_dirs in their manifest. See docs/build-selection.md. For symlinked skills in v1.7.2+, exclude their real parent, for example --exclude-dirs=.claude/skills. Precise production/test loading masks directory links beneath it without following targets. Linked Go inputs/metadata remain errors, and an existing Go overlay conflicts with masking. doc retains its independent strict preflight. Codex setup: docs/codex-integration.md.

The gograph binary must be installed and on $PATH:

go install github.com/ozgurcd/gograph/cmd/gograph@latest

Verify the active installation with gograph doctor --json; it reports the running binary, PATH resolution, shadowed copies, and—inside a repository—the current graph's freshness, analysis capabilities, and diagnostic without executing alternate binaries. The marketplace plugin supplies this workflow guidance; it does not install the binary or register an MCP server. Register gograph mcp <project-path> for each project using the client's MCP setup. Packaged and generated registrations keep refresh persistence off by default.

Mandatory workflow (enforced)

1. At the start of any Go coding session, run CLI gograph doctor --json to detect installation shadowing, then invoke gograph_capabilities to confirm what the connected server exposes.
2. Confirm graph health before symbol queries. MCP creates an in-memory AST graph when the artifact is missing, unreadable, unsafe, or has an unsupported source-policy marker, and refreshes source analysis per call. Invoke gograph_stats with no parameters and require build_status=complete; a build with zero successful parses never replaces the previous graph, while partial failures are reported explicitly. When durable precise enrichment is needed, run CLI gograph build . --precise; use gograph build . --precise --strict when CI must fail on fallback. If compilation prevents precision during exploratory work, use CLI gograph build . and explain the fallback.
3. For unfamiliar structural questions, invoke gograph_explore first; for complete structural symbol / type / function discovery, use gograph_query instead of grep, rg, find, or glob. Start with compact=true when identity and evidence counts are enough; use standard mode for direct evidence or deep=true for bounded depth-3 exact evidence, package context, and explanation. Compact/deep are mutually exclusive and default to 5/25 rows versus standard's 10; an explicit limit overrides the mode default. gograph_explore discloses lexical selection, ambiguity, totals, truncation, and omissions; follow with a focused tool when a complete section is needed. Text search also matches comments and string literals; gograph_query returns AST-derived matches. Continue to use text search for literal strings, documentation, ordinary non-sensitive configuration, and non-Go files.
4. Before editing any Go symbol, invoke gograph_plan with symbol=<symbol>. The plan returns callers, tests connected to the symbol, and a blast-radius estimate. Edit decisions should reference the plan.
5. To understand a function or method, invoke gograph_context with symbol=<symbol>. This single call combines node + source + callers + callees + statically mapped tests; inspect source or gopls when the evidence is incomplete.
6. After editing Go code, invoke gograph_review with uncommitted=true; MCP refreshes source analysis before the review. If the task requires a durable precise artifact for later CLI or server processes, run CLI gograph build . --precise first. Run the repository's required tests and checks separately.

MCP responses carry graph provenance in _meta and native structured content where supported. Common bounded row lists use gograph.results.v1; native explain/changes retain their schemas. Other legacy results retain a gograph.mcp-result.v1 (source/context instead use gograph.read.v1 with the answer or refusal) structured companion. Inspect the accompanying graph_state before using an absence or broad impact result: source, freshness, completeness, and precision are independent. A current in-memory fallback and a trusted stale persisted result are intentionally usable but degraded; disclose them and cross-check important negatives. A different effective Go build context fails closed rather than being served. CLI graph-backed --json responses expose the same gograph.graph-state.v1 object at the envelope top level.

High-value tools

Uncommitted modes compare declarations against HEAD. Incomplete comparisons, deleted declarations needing historical caller evidence, and missing/ambiguous current identities are explicit errors, not empty successful reviews. Inspect gograph_changes with git_ref=HEAD for deletions; rebuild before traversing new declarations. CLI uses the same rules.

The live surface is 68 MCP endpoints; gograph_capabilities is the tested source of truth. gograph_flow is path-insensitive with bounded call-site matching; use it for security review leads, not exploitability proof. Common list tools (including query, callers/callees, impact, types/usages, errors/envs, and httpcalls) default to 100 rows, maximum 200, within a 16 KiB native-page budget. Inspect total, returned, truncated, and next_cursor; follow cursors with the same snapshot and filters for a complete census. Changing page size is allowed. Snapshot or selection changes reject old cursors; restart the census. Never combine pagination with mermaid or files_only. Routes and SQL retain their specialized 64 KiB page contracts. gograph_explain returns ambiguity candidates instead of selecting a name twin. gograph_changes reuses recorded platform/build tags and rediscovers current module ownership; missing legacy selection or a racing source tree makes its evaluation incomplete. CLI incomplete changes exit 2.

gograph_httpcalls retains bounded lexical URL-base/static-suffix evidence and labels NewRequest/NewRequestWithContext as request construction, not dispatch proof. Workspace http_clients explicitly maps bases (cfg.API, env:API_URL) to logical authorities in the selected scope; no environment values are read. Workspace query retains http_unresolved diagnostics; verified status includes per-scope unresolved counts. Such diagnostics never participate in traversal. The four gograph_workspace_* tools require a separate workspace server and share native values with CLI workspace status/query/path/impact. For gograph_callers, gograph_callees, gograph_impact, gograph_endpoint, gograph_dependents, gograph_deps, gograph_path, and gograph_coupling, set mermaid=true to request Markdown-fenced Mermaid instead of the tool's normal response.

CLI path and MCP gograph_path share deterministic best-path selection: exact before possible, then shorter, production before tests, typed resolution before heuristics, and a canonical tie-breaker. Workspace path adds fewer cross-repository transitions as the final semantic preference.