Skip to content
Back to search

gograph

Local-only Go static analysis engine with a built-in MCP server. Gives AI coding agents deterministic structural awareness: call graphs, impact analysis, symbol search, and more.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ozgurcd/gograph with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ozgurcd/gograph'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ozgurcd--gograph/badge.svg)](/listings/ozgurcd--gograph)

HTML

<a href="/listings/ozgurcd--gograph"><img src="/api/listings/ozgurcd--gograph/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

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

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

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

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

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

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

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

Homebrew and `go install` install the normal `gograph` CLI. MCP clients that support MCP Bundles can instead discover the local stdio server in the [official MCP Registry](https://registry.modelcontextprotocol.io) 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](docs/mcp-registry.md) 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 24 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "gograph",
  3. "owner": {
  4. "name": "ozgurcd",
  5. "url": "https://github.com/ozgurcd"
  6. },
  7. "metadata": {
  8. "description": "Marketplace hosting the gograph Claude Code plugin - Go repository intelligence via MCP."
  9. },
  10. "plugins": [
  11. {
  12. "name": "gograph",
  13. "description": "Claude Code workflow guidance for local gograph: AST-aware call graphs, impact, security-flow candidates, and 61 query, analysis, and workflow capabilities through a separately registered MCP server.",
  14. "version": "0.1.0",
  15. "author": {
  16. "name": "ozgurcd",
  17. "url": "https://github.com/ozgurcd"
  18. },
  19. "source": "./",
  20. "category": "developer-tools",
  21. "homepage": "https://gograph.identuum.ai"
  22. }
  23. ]
  24. }
README.md · README · 572 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # gograph
  2. Symbol queries accept `path/to/file.go:Name`, including
  3. `path/to/file.go:Receiver.Method`, or an import-qualified file path when a short
  4. name is ambiguous. `file.go:Name` never matches a method; methods need
  5. `file.go:Receiver.Method`. `source` prints exact selectors for ambiguous
  6. matches, and every printed selector resolves to exactly one declaration.
  7. Supported declaration tools and named exceptions are listed in
  8. [the selector contract](docs/query-contracts.md#file-qualified-selectors).
  9. Queries include struct fields; `query --no-tests` excludes test-file rows.
  10. Precise mutation queries recover the type of fields assigned on returned values.
  11. Routes retain constant and unresolved path registrations; precise builds resolve
  12. constants across packages, including net/http method patterns.
  13. `tests --transitive --files-only` prints unique file paths, matching the files in
  14. the MCP transitive report.
  15. Graph-state output and capabilities expose `freshness_context`: CLI freshness
  16. checks use the querying process's Go context, including GOFLAGS; MCP uses its
  17. startup context and explicit tags. A context mismatch remains stale, even when
  18. source bytes have not changed. No environment values are printed.
  19. Precise indexes include package-level constant references in `usages` and `query`,
  20. including comparisons, switch cases, composite values, and function arguments.
  21. Typed enum-like constants retain their declaration identity; local shadows are excluded.
  22. `query` labels these reference sites as `usage` rows. AST-only graphs do not
  23. claim type-resolved constant usages.
  24. `review` uses the same test attribution as `context`. Rebuild after upgrading.
  25. `review --uncommitted` includes deleted declarations from `changes --git HEAD`
  26. and explicitly leaves historical callers, tests and risk unevaluated. Other
  27. current-graph traversal commands retain their deletion refusal. Builds explain
  28. when an enclosing Git repository ignores the requested directory.
  29. Uncommitted plan/review skip blank-identifier declarations such as
  30. `var _ I = (*T)(nil)` during symbol traversal. Review keeps their declaration
  31. evidence and names the limit; `changes --git HEAD` still lists them.
  32. Session audits list invocation errors separately from operational failures and
  33. exclude them from compliance scoring. Composability measures the mix of composed
  34. and raw query commands; it does not measure answer correctness or token savings.
  35. [![Go Report Card](https://goreportcard.com/badge/github.com/ozgurcd/gograph)](https://goreportcard.com/report/github.com/ozgurcd/gograph)
  36. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  37. [![Go Version](https://img.shields.io/github/go-mod/go-version/ozgurcd/gograph)](https://github.com/ozgurcd/gograph)
  38. [![Homebrew](https://img.shields.io/badge/homebrew-available-orange)](https://github.com/ozgurcd/homebrew-tap)
  39. [![Docs](https://img.shields.io/badge/docs-gograph.identuum.ai-blue)](https://gograph.identuum.ai)
  40. **Give Go coding agents a compiler-aware map for safer refactors.**
  41. `gograph` builds a local structural graph of your Go repository, with optional
  42. type-checked CHA/SSA enrichment. Its CLI and MCP workflows help coding agents
  43. trace callers and interface implementations, plan change impact, and enforce
  44. architecture without embeddings or a hosted code index.
  45. **[Explore the interactive no-install demo](https://gograph.identuum.ai/demo/)** ·
  46. **[Review the reproducible benchmark](docs/benchmarking.md)**
  47. See [CLI/MCP query contracts](docs/query-contracts.md) for bounded result pages,
  48. snapshot-bound cursors, exact/possible impact, and change-evaluation status.
  49. **Companion projects:** [Scrinium](https://github.com/ozgurcd/scrinium)
  50. provides repository-owned, evidence-backed knowledge for coding agents, while
  51. [Rulefloor](https://github.com/ozgurcd/rulefloor) protects repository-local
  52. invariants by binding them to concrete tests and detecting drift. They are
  53. independent, optional tools: Scrinium can keep Gograph structural observations
  54. and Rulefloor validation results as separate evidence without treating either
  55. as proof of unrelated behavior or global project correctness.
  56. ![Gograph Demo](gograph-demo.gif)
  57. > **Static analysis; no target-code execution.** Default indexing parses Go source locally and does not call application services. Linked directories and linked/special files for extensions recognized by `go/build` are excluded; unrelated regular-file or dangling links with non-Go extensions are not Go tool inputs and do not block precise analysis. Graph-directed source reads remain confined to regular files beneath the analyzed repository, and linked/non-regular Go tool metadata (`go.mod`, `go.sum`, `go.work`, `go.work.sum`, and `vendor/modules.txt`) is rejected before toolchain invocation; an explicitly symlinked repository root remains supported. Applicable `go.work use` members may be sibling modules beneath the nearest real Git checkout; without that boundary they remain confined beneath the workspace directory. Each member directory, `go.mod`, and optional `go.sum` is validated before `cmd/go` starts. Gograph also reads project metadata such as `.gitignore`, graph/config JSON, and Git state. Indexing asks the installed Go toolchain for the effective build/module context; precise mode additionally performs package type loading, and `doc` runs `go doc`. Those operations follow your configured module/cache/network policy. Before repository package loading or `go doc`, applicable local module/workspace source trees are preflighted for links that `cmd/go` may inspect; `.git` and `.gograph` subtrees are excluded. Session telemetry is local under `.gograph/sessions/`; nothing is sent to gograph services.
  58. ## Quick Start
  59. ```bash
  60. # Install
  61. brew install --cask ozgurcd/tap/gograph
  62. # or: go install github.com/ozgurcd/gograph/cmd/gograph@latest
  63. # Confirm which installation will run and detect PATH shadowing
  64. gograph doctor --json
  65. # Build a type-enriched precise graph, then verify it
  66. gograph build . --precise
  67. gograph stats
  68. # Optional CI contract: fail when precise enrichment falls back
  69. gograph build . --precise --strict
  70. # Optional: prioritize lower heap use on constrained hosts
  71. gograph build . --precise --memory-mode=low --max-memory=1GiB
  72. # Optional: include integration-tagged files and tests in this graph
  73. gograph build . --precise --tags=integration
  74. # Optional: omit unrelated broken package directories
  75. gograph build . --precise --strict --exclude-dirs=legacy,examples/broken
  76. # Start with repository-wide results that require no guessed symbol
  77. gograph summary
  78. gograph hotspot --top 5
  79. gograph flow --no-tests
  80. ```
  81. **Two things to know before you start**
  82. - **CLI or MCP.** CLI analysis commands read `.gograph/graph.json`, so run
  83. `gograph build .` (or `gograph build . --precise`) first; without it they stop
  84. with `run 'gograph build' first`. The MCP server needs no build step:
  85. `gograph mcp` builds an in-memory graph when no usable one exists, rebuilds
  86. changed packages before a call when source files changed, and writes no graph
  87. files unless started with `--persist-refresh`.
  88. - **Your Go toolchain may use the network.** gograph itself sends nothing. It
  89. runs your installed `go` command with your environment: every build and
  90. freshness check asks `go` for the build context, `--precise` loads packages
  91. through `go list`, and `doc` runs `go doc`. Go can therefore download missing
  92. modules or a newer toolchain, as your `GOPROXY`, `GOTOOLCHAIN` and `GOFLAGS`
  93. allow. To keep runs offline, set `GOPROXY=off GOTOOLCHAIN=local`; a module
  94. missing from the cache then makes `--precise` fall back to the AST graph
  95. (`precision: precise_fallback`) instead of downloading. For packages that use
  96. cgo, `--precise` also invokes your C compiler (it compiles, never runs, the
  97. code).
  98. Homebrew and `go install` install the normal `gograph` CLI. MCP clients that
  99. support MCP Bundles can instead discover the local stdio server in the
  100. [official MCP Registry](https://registry.modelcontextprotocol.io) as
  101. `io.github.ozgurcd/gograph`. Registry/MCPB installation is a separate
  102. distribution path; it does not install the Homebrew cask or configure the
  103. Claude Code marketplace plugin. The Registry is currently in preview. See
  104. [Official MCP Registry and MCPB installation](docs/mcp-registry.md) for client
  105. support, target selection, and current limitations.
  106. Choose a real function or method shown by `summary`, `hotspot`, or
  107. `gograph complexity`, then substitute its name below:
  108. ```bash
  109. gograph explore "YourSymbol" --compact # low-token discovery, identity/role, and complete evidence counts
  110. gograph explore "YourSymbol" # standard source + callers/callees + tests + exact identity impact
  111. gograph explore "YourSymbol" --deep # standard response + depth-3 exact evidence, package context, explanation
  112. gograph context "YourSymbol" # source + callers + callees + tests
  113. # For compilable repositories, enrich the graph before a major refactor
  114. gograph build . --precise
  115. gograph plan "YourSymbol"
  116. ```
  117. Build artifacts are written under the target `.gograph/` directory. `gograph`
  118. adds `.gograph/` to the enclosing Git repository root `.gitignore` when
  119. available, falls back to the build target `.gitignore` outside Git, and exits
  120. without replacing artifacts if no Go files are found or no source file parses
  121. successfully. The update accepts only an absent or regular `.gitignore`; a
  122. repository-provided link is refused and its target is not modified. Go build
  123. constraints, explicit comma-separated `--tags` (or inherited `GOFLAGS` when
  124. the flag is absent), cmd/go package-directory rules, generated
  125. sources, module-mode ignore directives, and Git ignores use the same scanner
  126. policy for building, freshness checks, and change detection. Linked `.go`
  127. files, linked directories, and other non-regular recognized Go inputs are
  128. reported and excluded. Unrelated regular-file and dangling links with non-Go
  129. extensions (for example YAML configuration or TSV fixtures) are ignored by
  130. Go-tool preflight;
  131. linked/non-regular `go.mod`, `go.sum`, `go.work`, `go.work.sum`, and
  132. `vendor/modules.txt` entries are rejected before gograph or the Go toolchain
  133. reads them. Applicable `go.work use` members may be sibling modules beneath the
  134. nearest real Git checkout. Non-Git layouts retain workspace-directory
  135. confinement, nested Git boundaries are not crossed, and every member directory,
  136. `go.mod`, and optional `go.sum` is validated before `cmd/go` starts.
  137. `.gograph` itself must be a real directory, and `graph.json` must be a regular
  138. repository-confined file. Graphs with a missing or unsupported confinement
  139. policy marker must be rebuilt with the current binary before graph-backed
  140. commands use them. Older binaries do not enforce this boundary and should not
  141. be used to analyze untrusted repositories.
  142. Each indexed source file stores a SHA-256 content digest. Rebuilds reparse all
  143. selected files in a changed package together and reuse parser records for
  144. unchanged packages; `stats` reports `reused_files` and `rebuilt_packages`.
  145. Precise builds reuse that AST work but still recompute repository-wide
  146. type/CHA/SSA enrichment so cross-package dispatch remains correct.
  147. Low-memory mode preserves those graph semantics while using more aggressive
  148. garbage collection, reclaiming memory between production and test analysis,
  149. and avoiding a full JSON copy of the AST graph. `--max-memory` accepts integer
  150. byte sizes such as `1GB` or `1GiB` and requires `--memory-mode=low`. It is a
  151. soft Go-runtime memory target—not a hard RSS cap—so memory-mapped files,
  152. the executable, and Go toolchain subprocesses can make process memory exceed
  153. the requested value. Aggressive GC can increase CPU time, and a target that is
  154. too low may make the build much slower or fail; Gograph never silently reduces
  155. precision to meet it.
  156. Precise fallback continues to exit zero by default for compatibility and is
  157. recorded in graph metadata. Add `--strict` with `--precise` when fallback must
  158. fail CI; Gograph still publishes or retains the diagnostic artifact before
  159. returning non-zero.
  160. For precise builds blocked by unrelated directories, see
  161. [directory exclusions](docs/build-selection.md). Use the same `--exclude-dirs`
  162. selection on `gograph mcp` startup; imported dependencies must still type-check.
  163. For symlinked skills, v1.7.2 supports `--exclude-dirs=.claude/skills`: directory
  164. links beneath that real directory are hidden from Go loading, without following
  165. their targets. Linked Go inputs and metadata remain protected. See the
  166. [Codex MCP setup guide](docs/codex-integration.md) for registration and verification.
  167. ## Machine-readable structural validation
  168. External consumers can validate one closed structural predicate without
  169. parsing human CLI output:
  170. ```bash
  171. gograph version --json
  172. gograph validate --repo /work/project --binding-json '{"schema_version":"gograph.binding.v1","predicate":"symbol_exists","subject":{"language":"go","kind":"symbol","id":"example.com/project/internal/auth::Authorize"},"required_precision":"ast"}' --json
  173. ```
  174. The version and result schemas are `gograph.version.v1` and
  175. `gograph.validation.v1`; bindings use `gograph.binding.v1`. V1 supports
  176. `symbol_exists`, `package_imports`, `call_edge_exists`, `type_implements`, and
  177. the policy predicates `imports_only_from`, `callers_only_from` and
  178. `call_arg_constant`, which report every violating file:line.
  179. Validation is read-only and never builds or refreshes the graph. Exit `0` means
  180. `pass`, exit `1` means a conclusively evaluated `fail`, and exit `2` means
  181. `cannot_evaluate` or an invalid request.
  182. Negative results require predicate-specific completeness: symbol and direct
  183. import absence need a current complete AST graph; implementation absence needs
  184. a current precise-complete graph; call absence additionally requires complete
  185. resolution of the subject's relevant call edges. Missing, stale, partial,
  186. ambiguous, or unresolved evidence degrades to `cannot_evaluate`; a
  187. `precise_fallback` graph may support AST presence but never evaluated absence.
  188. The result binds the exact graph bytes, selected source/build-context manifest,
  189. and canonical binding with SHA-256 fingerprints.
  190. Gograph validates selected-build-context Go structure. It does not prove
  191. runtime behavior or business correctness. CHA edges are possible static targets,
  192. not runtime dispatch certainty. V1 excludes reachability, unstable or external
  193. symbol identities, unnamed types, and non-Go languages. See the exact
  194. [machine-validation contract](docs/machine-validation-contract.md).
  195. Applicable local module/workspace source roots must remain beneath the explicit
  196. `--repo` root; v1 returns `cannot_evaluate` instead of widening that authority.
  197. MCP refreshes stay in memory by default. To publish each successful refresh
  198. for CLI consumers and later server processes, start the server explicitly with:
  199. ```bash
  200. gograph mcp . --persist-refresh
  201. # Keep MCP startup and every later refresh on the integration-tagged selection:
  202. gograph mcp . --tags=integration
  203. # Optional low-memory policy for startup analysis and later refreshes:
  204. gograph mcp . --memory-mode=low --max-memory=1GiB
  205. ```
  206. This opt-in mode writes or overwrites `.gograph/graph.json` and the nine
  207. Markdown reports after a confirmed-fresh refresh. It does not modify
  208. `.gitignore`, so ignore `.gograph/` yourself before enabling it when needed.
  209. The directory holds only the latest published state; it is not a per-branch
  210. cache. If no usable graph exists (including an unsafe or unsupported artifact),
  211. the startup auto-build is published before serving;
  212. a failure there prevents startup. A later tool-triggered publication failure
  213. makes that tool return an error, and the server retries the pending publication
  214. on another refresh-capable call without rebuilding the already-fresh in-memory
  215. graph. Writers coordinate through a local `.gograph/.artifacts.lock` file; an
  216. existing lock entry must be regular rather than a link or special file.
  217. Reports are replaced first and `graph.json` is replaced last as the publication
  218. commit marker; the complete ten-file bundle is not a single atomic filesystem
  219. transaction. Same-directory replacement is atomic on Unix-like systems; Go
  220. does not guarantee atomic rename semantics on non-Unix platforms. The lock
  221. file remains as operational coordination state in addition to the ten outputs.
  222. Persisted graphs are bound to their effective Go environment and build
  223. selection. Start MCP with the same `GOWORK`, `GOFLAGS`, and `--tags` context
  224. used to build the graph; a mismatch is stale and must refresh successfully or
  225. return a diagnostic rather than silently serving incompatible facts.
  226. `gograph doctor --json` reports that repository diagnostic.
  227. ## Why gograph?
  228. *Illustrative point-in-time output comparison from an earlier gograph revision
  229. (counts vary as the repository evolves; these commands return different kinds
  230. of evidence):*
  231. | Task | `grep -rn` | `gograph` | Observed output difference |
  232. |---|---|---|---|
  233. | Find callers of `loadGraph` | 158 matching lines (comments, docs, vars) | 56 AST-derived call-site rows | ~65% fewer rows in that run |
  234. | Locate symbol definitions | 842 lines matching "Symbol" | 83 true type/method declarations | ~90% noise eliminated |
  235. | Read one function body | `cat` displays 180+ lines of the whole file | `source` extracts the 12-line function | ~93% fewer source lines in that run |
  236. | Gather common symbol context | Separate node, source, caller, callee, and test queries | `context` bundles those fields | Five evidence types in one response |
  237. ## Key Features
  238. **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 →](https://gograph.identuum.ai/docs/command-reference/)
  239. **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 →](docs/workspaces.md)
  240. **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 →](https://gograph.identuum.ai/docs/command-reference/#cli--mcp-transport-matrix)
  241. **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.
  242. **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.
  243. **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.
  244. **Architecture Enforcement** — boundary rules, API drift detection, complexity gates, dead code sweeps, god-object detection, coupling analysis. Run in CI with `gograph gate`.
  245. **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`.
  246. **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.
  247. **Agent Compliance Auditing** — session telemetry tracks whether agents run `plan` before edits and `review` after. Grades agent behavior A–F with actionable recommendations.
  248. Audit sessions belong to an explicit caller. `gograph session create task` prints
  249. the session ID; pass it on subsequent CLI commands with `--session-id ID` or
  250. `GOGRAPH_SESSION=ID`. The flag overrides the environment. Selected analytical
  251. commands retain the `--intention` requirement and existing audit grades. Agent
  252. shells usually do not keep `GOGRAPH_SESSION` between commands, so a CLI command
  253. without a selector uses the repository's only active session when this host's CLI
  254. created it; that covers `build`, `plan`, `review`, and `session end`. When
  255. several sessions are active, or the only one is MCP-owned, from another host, or
  256. lacks owner metadata, nothing is adopted: read-only commands then require no
  257. intention and never write to another caller's audit. `gograph session end ID`
  258. ends a named session.
  259. A session its job forgot cannot block later jobs: every CLI command and MCP
  260. call first ends other callers' abandoned sessions, meaning CLI sessions with no
  261. activity for `GOGRAPH_SESSION_IDLE_LIMIT` (a Go duration, default `2h`; `0` or
  262. `off` disables) and sessions of MCP servers that have exited on this host. It
  263. prints each one it ends on stderr. Refused calls do not count as activity, and
  264. a call's own selected session is never ended. The forgotten owner's next call
  265. reports that its session was ended as abandoned. Independent callers may create separate sessions concurrently.
  266. Repository writes and session end/cleanup refuse while another caller owns an
  267. active session, naming that session. Ending an owned session remains possible
  268. while other owners are active. Unset `GOGRAPH_SESSION` after ending it.
  269. MCP tools accept `session_id` and `intention` per request. Use the ID returned by
  270. `gograph_session_create`; analytical owner calls require a rationale. The server
  271. does not inherit `GOGRAPH_SESSION`, so sharing one MCP process does not merge
  272. callers. Default in-memory refresh remains read-only; `--persist-refresh` calls
  273. are guarded as writes. Session IDs are cooperative attribution selectors, not
  274. credentials or an OS-user security boundary. Older active sessions can be
  275. selected explicitly by their existing ID. See the [session design](llm-wiki/session-scope.md).
  276. ## Command Reference
  277. Query and composed-analysis commands support `--json`; `version --json` and
  278. `validate ... --json` use their dedicated machine schemas. The exact `--files-only`
  279. surface is listed in the command reference. Operational commands such as
  280. `build`, `wiki`, `gate`, `snapshot`, installation, and help use text
  281. output; `doctor` and workspace build/status/query/path/impact also accept `--json`, and
  282. `session audit` additionally supports raw JSON. CLI `--mermaid` renders
  283. `callers`, `callees`, `impact`, `endpoint`, `dependents`, `deps`, `path`, and
  284. `coupling` as fenced Mermaid. Their MCP equivalents accept `mermaid=true` and
  285. return the same Markdown-fenced Mermaid text; without it, each tool retains its
  286. normal response format.
  287. | Category | Commands | What it does |
  288. |---|---|---|
  289. | **Indexing** | `build . [--precise] [--strict] [--memory-mode=low] [--max-memory=1GiB]`, `stale`, `stats` | Parse AST, optionally require precise success or prioritize lower heap use, write graph, check freshness and health. |
  290. | **Machine Validation** | `version --json`, `validate --repo PATH --binding-json JSON --json`, `whatsnew [--since vX.Y.Z] [--json]` | Versioned exact structural and policy predicates with tri-state outcomes; release notes for the running binary. |
  291. | **Navigation** | `query`, `callers [--depth N]`, `callees [--depth N]`, `path`, `source`, `node` | Find symbols, trace call chains, extract source. |
  292. | **Context** | `context`, `explain`, `focus`, `endpoint` | Bundled structural data in one call. Token savers. |
  293. | **Change Analysis** | `plan`, `review`, `risk`, `impact [--uncommitted\|--since]`, `changes [--git]`, `api --since` | Pre-edit planning, post-edit review, risk analysis, blast radius, drift. |
  294. | **Architecture** | `boundaries`, `coupling`, `complexity [--no-tests] [--top N] [--path DIR]`, `godobj`, `orphans`, `arity` | Quality gates, dead code, coupling, god objects. Policies live in the committable `gograph/` directory (`.gograph/` still read). |
  295. | **Types & Structs** | `fields`, `implementers [--test-only]`, `interfaces`, `embeds`, `constructors`, `literals`, `usages`, `mutate`, `schema` | Struct fields, interface satisfaction, type usage. |
  296. | **Infrastructure** | `routes [term] [--module MODULE] [--include-tests] [--limit N] [--cursor CURSOR]`, `sql [term] [--table T] [--verb V] [--access read\|write\|ddl] [--function F] [--module M] [--no-tests] [--limit N] [--cursor C]`, `envs`, `errors`, `concurrency`, `globals`, `httpcalls`, `deps [--transitive]`, `dependents`, `imports` | 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. |
  297. | **Security** | `flow [term] [--source kind] [--sink kind] [--config path] [--no-tests] [--package path]... [--max-work N] [--context-depth N]` | 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 `parameter_only`. |
  298. | **Testing** | `tests [symbol] [--transitive] [--exact-only] [--package name] [--max-depth N] [--limit N] [--cursor T]`, `tests --uncommitted`, `tests --since <ref>`, `tests <symbol> --format go-test`, `coverage <TestFunc> [--exact-only] [--package name]`, `untested [--pkg name] [--top N] [--exclude glob] [--wide] [--exclude-interface-methods] [--coverprofile file]`, `uncovered --uncommitted\|--since <ref> --coverprofile file`, `fixtures`, `mocks` | Direct and transitive reverse exact/possible static test attribution, runnable per-package `go test -run` selection for a change, one-sweep gap census, runtime coverage gaps and unexecuted changed lines, full stable-ID output, helpers, mock implementations. |
  299. | **Error Tracing** | `errorflow [--no-tests]`, `trace` | Reverse-BFS from error strings to HTTP entry points. |
  300. | **Diagnostics** | `doctor [--json]`, `hotspot`, `returnusage`, `skeleton`, `diagram`, `changes`, `public` | Install/PATH plus current graph freshness/capability diagnostics, hotspots, return usage, API signatures, Mermaid diagrams. |
  301. | **CI/CD** | `check [--since\|--uncommitted]`, `gate`, `snapshot save\|diff\|list\|drop` | Policy checks, threshold enforcement, metric snapshots. |
  302. | **Telemetry** | `session create\|end\|audit\|cleanup` | Agent compliance tracking and grading (A–F). |
  303. | **LLM-Wiki** | `wiki [--output dir]` | Generate `llm-wiki/` and prune obsolete generator-owned package pages while preserving custom pages and `packages/README.md`. |
  304. | **Summary** | `summary [--json]` | Single-call codebase briefing: top 3 hotspots, worst instability package, highest complexity function, orphan count, god-object count. Replaces 5 separate calls. |
  305. | **Stable IDs** | `identity <symbol-or-stable-id> [--package name] [--json]` | Print and re-resolve module/package/receiver/name identity that survives line shifts and file moves inside a package; package disambiguates external-test collisions. |
  306. | **Reverse Attribution** | `coverage <TestFunc> [--exact-only] [--package name] [--json]` | Transitive product-symbol set for one unambiguous test, with stable-ID paths and exact/possible propagation. Static evidence only—not runtime or branch coverage. |
  307. | **Tests reaching a symbol** | `tests <symbol> --transitive [--exact-only] [--package name] [--max-depth N] [--limit N] [--cursor T] [--json]` | 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` remains direct for compatibility. |
  308. | **Tests to run** | `tests --uncommitted\|--since <ref> [--format run\|go-test] [--max-depth N] [--exact-only]`, `tests <symbol> --format go-test` | Which tests to run for a change: per package, anchored `-run` patterns and ready `go test` commands with the graph's `-tags`; unselectable declarations are listed, never dropped. |
  309. | **Untested** | `untested [--pkg name] [--top N] [--exclude glob] [--wide] [--exclude-interface-methods] [--coverprofile file] [--json]` | Called production symbols without an exact transitive test path, `none` before `possible`. Precise builds devirtualize only proven concrete receivers; open interface paths remain `test_resolution=possible`. `--exclude-interface-methods` skips Error/String-style methods; `--coverprofile` lists functions a `go test -coverprofile` run never executed. JSON includes `stable_id`; `--wide` prints it without truncation. |
  310. | **Uncovered changes** | `uncovered --uncommitted\|--since <ref> --coverprofile file [--json]` | Changed lines of non-test Go files that a coverage profile shows were never executed, as exact ranges. |
  311. | **Doc** | `doc <pkg[.Symbol]> [--json]` | `go doc` wrapper — signature + doc comment for any stdlib or third-party symbol. No graph required. Closes the gap when call chains leave the project. |
  312. Precise `implementers` results merge type-checked production types with
  313. AST-discovered test-file fakes; `--test-only`/MCP `test_only=true` returns only
  314. the latter. Direct `tests` lookup accepts `Receiver.Method` (including pointer
  315. receivers) or a stable ID. `usages` covers signature/field/interface references
  316. and `Foo{...}` construction. Precise indexes also include package variables and
  317. constants referenced in expressions; `literals` remains the focused
  318. construction-only view.
  319. SQL extraction includes direct literals and statically resolvable local or
  320. same-file package `const`/`var` declarations, straight-line assignments, and
  321. bounded string concatenations. Runtime-generated SQL remains excluded. Route and SQL JSON are
  322. paged row censuses; `--files-only` follows all pages but emits a complete
  323. deduplicated **file** census, not every row.
  324. > Full command reference with examples: [gograph.identuum.ai/docs/command-reference](https://gograph.identuum.ai/docs/command-reference/)
  325. <details>
  326. <summary><strong>Architecture Boundary Enforcement</strong></summary>
  327. Define boundaries in the committable `gograph/boundaries.json` (`.gograph/boundaries.json`, which gograph git-ignores, is still read when no committed file exists):
  328. ```json
  329. {
  330. "layers": [
  331. { "name": "domain", "packages": ["internal/domain/**"], "may_import": [] },
  332. { "name": "handler", "packages": ["internal/handler/**"], "may_import": ["internal/service/**", "internal/domain/**"] }
  333. ]
  334. }
  335. ```
  336. Run `gograph stale` (and rebuild when stale) before `gograph boundaries`; the
  337. CLI evaluates the persisted graph and exits with code 1 on violation. The
  338. default policy is `gograph/boundaries.json`, else `.gograph/boundaries.json`; use `--config PATH` for another
  339. regular, repository-confined policy. MCP uses the same evaluation after its
  340. normal source refresh. Works in CI/CD.
  341. </details>
  342. <details>
  343. <summary><strong>Security flow sanitizer policy</strong></summary>
  344. `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:
  345. ```json
  346. {
  347. "sanitizers": [
  348. { "function": "security.CleanPath", "for": ["filesystem"] },
  349. { "function": "security.ValidateURL", "for": ["outbound_http"] }
  350. ]
  351. }
  352. ```
  353. 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.
  354. </details>
  355. ## AI Agent Integration
  356. **Official MCP Registry (preview):** MCPB-capable clients can discover
  357. `io.github.ozgurcd/gograph`. The bundle asks for the root directory of the Go
  358. project and launches the bundled executable with separate arguments equivalent
  359. to `gograph mcp <project-directory>`. Releases provide macOS, Linux, and
  360. Windows bundles for both amd64 and arm64. The current Registry package schema
  361. cannot select by CPU architecture, so choose the asset whose filename matches
  362. the host; do not assume a client will select it automatically. All analysis
  363. still runs locally over stdio, with no hosted gograph service or remote
  364. telemetry.
  365. The Registry bundle and installer-generated MCP registrations intentionally omit
  366. `--persist-refresh`, keeping disk publication off by default. Use a custom
  367. local MCP command if you explicitly want that behavior.
  368. **Desktop config, shared rules, and Claude Code hook setup:**
  369. ```bash
  370. gograph add-claude-plugin
  371. ```
  372. This 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.
  373. **Alternative — install via Claude Code plugin marketplace:**
  374. ```bash
  375. /plugin marketplace add ozgurcd/gograph
  376. /plugin install gograph@gograph
  377. ```
  378. Discovers 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.
  379. 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.
  380. **Other agents** (Cursor, Copilot, Antigravity, etc.):
  381. ```bash
  382. gograph mcp . # stdio server; refreshes stay in memory
  383. gograph mcp . --persist-refresh # opt in to publishing refreshed artifacts
  384. gograph mcp . --tags=integration # retain the same tagged context on every refresh
  385. gograph mcp . --memory-mode=low --max-memory=1GiB # same low-memory refresh policy as CLI builds
  386. ```
  387. Add to your `.cursorrules` or AI system prompt:
  388. > Before answering architecture or repository questions, inspect the available
  389. > `gograph_*` MCP tools and run `gograph capabilities`. Prefer gograph for
  390. > supported structural queries; use `gopls` or targeted source/text search when
  391. > results are ambiguous, precision fell back, or a known source call is missing.
  392. Query and composed-analysis commands support `--json` for machine-readable output:
  393. ```bash
  394. gograph callers "YourSymbol" --json
  395. # → {"schema_version": "1", "command": "callers", "status": "ok", "count": 2, "results": [...]}
  396. ```
  397. For full integration guides, see [docs/coding-agent-usage.md](docs/coding-agent-usage.md).
  398. **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:
  399. ```bash
  400. gograph build . --precise
  401. gograph wiki # writes to ./llm-wiki/
  402. # generated orientation starts at: llm-wiki/overview.md
  403. # if maintained governance pages exist, read:
  404. # llm-wiki/index.md → project.md → agent-rules.md → agent-contract.md
  405. ```
  406. Add generated wiki output to `.gitignore` when it is disposable. Do not
  407. overwrite a repository's maintained or Scrinium-protected `agent-rules.md`;
  408. propose governed changes through that repository's documented workflow.
  409. Regeneration removes only obsolete package pages that match Gograph's generated
  410. signature; custom package pages and `packages/README.md` are preserved.
  411. ## Example Output
  412. When you run `gograph build .`, the generated `GRAPH_REPORT.md` gives your AI a condensed context map:
  413. **External Dependencies (Tech Stack)**
  414. | Module | Version |
  415. |--------|---------|
  416. | `github.com/gin-gonic/gin` | `v1.9.1` |
  417. | `github.com/jackc/pgx/v5` | `v5.5.5` |
  418. **Important Symbols (Top by outgoing calls)**
  419. | Symbol | Kind | File | Line | Calls out |
  420. |--------|------|------|------|-----------|
  421. | `(Server).Start` | method | `server.go` | 42 | 18 |
  422. | `ValidateAuth` | function | `auth.go` | 12 | 14 |
  423. ---
  424. ## How does gograph complement `gopls`?
  425. [`gopls`](https://go.dev/gopls/features/mcp) is the Go project's
  426. compiler-backed language server. It provides live workspace diagnostics,
  427. navigation, references, implementations, refactoring support, and an
  428. experimental MCP server. It should remain the first choice for editor and
  429. compiler-aware workspace operations.
  430. `gograph` adds a different layer for repository and agent workflows:
  431. 1. **Persisted snapshots** — CLI analysis can inspect a stable graph artifact,
  432. while MCP refreshes source-analysis state and preserves the requested
  433. precision mode.
  434. 2. **Repository-level analyses** — change impact, reachability, routes, SQL,
  435. environment reads, security-flow candidates, coupling, and policy gates are
  436. represented together.
  437. 3. **Composed responses** — `context`, `plan`, `review`, and `summary` package
  438. related evidence for agent workflows rather than exposing only one language
  439. operation at a time.
  440. Use `gopls` for live compiler-backed navigation and refactoring, `rg` for text
  441. and non-Go searches, and gograph when a persisted repository graph or composed
  442. change-analysis workflow is useful. See [the benchmark guidance](docs/benchmarking.md)
  443. for how to measure these different workflows without assuming one tool is a
  444. drop-in replacement for another.
  445. <details>
  446. <summary><strong>Correctness model</strong></summary>
  447. - **Default mode** uses Go AST parsing and best-effort heuristics. Tolerates incomplete or non-compiling repositories.
  448. - **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-regular `go.mod`, `go.sum`, `go.work`, `go.work.sum`, and `vendor/modules.txt` metadata is rejected before gograph or the Go toolchain reads it. Applicable `go.work use` paths 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 optional `go.sum` are validated before `cmd/go`. Precise loading and `doc` preflight the selected root plus its effective module root, or the workspace root and every member tree; `.git` and `.gograph` are excluded from that source-tree walk. Persisted `graph.json` is also read through this boundary, `.gograph` must 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.
  449. - **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; `--strict` requires `--precise` and returns non-zero after publication or retention. Successful and AST-only builds record `precise` and `ast` respectively. Test packages are loaded in a separate non-fatal typed pass: broken tests yield `typed_partial` test-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.
  450. - **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.
  451. - 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.
  452. - 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, and `typed_partial` means some tests stayed on parser heuristics.
  453. - Callback references are retained only when they resolve to repository callables, and exact call edges are deduplicated before serialization.
  454. - Mutation queries ignore ordinary local assignments and retain owning type information when statically known, so `Type.Field` disambiguates same-named fields.
  455. - Synchronization extraction requires a receiver tied to a known `sync` type. Error messages come from `panic`, `errors.New`, and `fmt.Errorf`, including import aliases.
  456. - 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.
  457. - 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 . --precise` supplies 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.
  458. </details>
  459. <details>
  460. <summary><strong>Non-goals</strong></summary>
  461. - No multi-language parsing
  462. - No AI/model API calls
  463. - No embeddings or SaaS backend
  464. - No remote telemetry or hosted analytics (optional audit sessions write local metadata only)
  465. - No replacement for compiler/type-checker correctness
  466. </details>
  467. ## Contributing
  468. Pull requests welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for build, test, and contribution guidelines.
  469. > **Language Support:** `gograph` currently parses Go only. The architecture is extensible — if you want to add Python, TypeScript, Rust, etc., please open an issue first.
  470. ## License
  471. MIT — see [LICENSE](LICENSE).
  472. [![gograph MCP server](https://glama.ai/mcp/servers/ozgurcd/gograph/badges/score.svg)](https://glama.ai/mcp/servers/ozgurcd/gograph)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.