https://github.com/ozgurcd/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.
https://github.com/ozgurcd/gograph
agentic-coding ai-agent ai-coding-assistant antigravity ast claude-code cli code-analysis code-navigation developer-tools go golang mcp-server opencode static-analysis
Last synced: 6 days ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/ozgurcd/gograph
- Owner: ozgurcd
- License: mit
- Created: 2026-05-08T23:15:18.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-10T03:44:46.000Z (11 days ago)
- Last Synced: 2026-06-10T05:20:33.580Z (11 days ago)
- Topics: agentic-coding, ai-agent, ai-coding-assistant, antigravity, ast, claude-code, cli, code-analysis, code-navigation, developer-tools, go, golang, mcp-server, opencode, static-analysis
- Language: Go
- Homepage: https://github.com/ozgurcd/gograph
- Size: 38.4 MB
- Stars: 170
- Watchers: 1
- Forks: 12
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# gograph
[](https://goreportcard.com/report/github.com/ozgurcd/gograph)
[](https://opensource.org/licenses/MIT)
[](https://github.com/ozgurcd/gograph)
[](https://github.com/ozgurcd/homebrew-tap)
[](https://gograph.identuum.ai)
**Stop burning tokens on `grep`. Give your AI agent a graph.**
`gograph` builds a local, AST-aware call graph of your Go repository and exposes **50+ query tools** via CLI and MCP so coding agents can navigate packages, symbols, call chains, routes, SQL, env vars, and tests — without reading raw files.
> **Zero network. Zero execution. Zero secrets read.** `gograph` is purely static analysis — it never runs your code, makes API calls, or opens non-`.go` files.
## Quick Start
```bash
# Install
brew install ozgurcd/tap/gograph
# Build the graph
gograph build . --precise
# Try it — who calls ValidateToken?
gograph callers "ValidateToken"
# Full context in ONE call (node + source + callers + callees + tests)
gograph context "ValidateToken"
# Change plan before editing (callers, tests, routes, SQL, env risk)
gograph plan "ValidateToken"
```
## Why gograph?
*Benchmarked on gograph's own codebase (70 files, 518 symbols, 16 packages):*
| Task | `grep -rn` | `gograph` | Savings |
|---|---|---|---|
| Find callers of `loadGraph` | 158 noisy lines (comments, docs, vars) | 56 exact structural call sites | ~65% noise eliminated |
| Locate symbol definitions | 842 lines matching "Symbol" | 83 true type/method declarations | ~90% noise eliminated |
| Read one function body | `cat` dumps 180+ lines of the whole file | `source` extracts the exact 12-line function | ~93% fewer tokens |
| Understand a symbol fully | 4–5 separate tool calls | 1 call: `context` bundles everything | 80% fewer tool calls |
## Key Features
**50+ Query Tools** — callers, callees, impact, context, plan, review, errorflow, orphans, hotspot, coupling, and more. Full [command reference →](https://gograph.identuum.ai/docs/command-reference/)
**Native MCP Server** — all tools available as MCP endpoints for Claude, Cursor, Copilot, and any MCP-compatible agent. One command setup: `gograph add-claude-plugin`
**Token-Saving Composites** — `context` replaces 5 calls. `plan` replaces 8. `explain` synthesizes architectural narratives. Built to minimize agent round-trips.
**Safe by Design** — no network, no code execution, no secrets, no `.env` files read. AI worktree directories (`.claude/`, `.cursor/`, `.agents/`) auto-excluded.
**Architecture Enforcement** — boundary rules, API drift detection, complexity gates, dead code sweeps, god-object detection, coupling analysis. Run in CI with `gograph gate`.
**Agent Compliance Auditing** — session telemetry tracks whether agents run `plan` before edits and `review` after. Grades agent behavior A–F with actionable recommendations.
## Command Reference
All commands support `--json` for machine-readable output and `--files-only` for flat file lists.
| Category | Commands | What it does |
|---|---|---|
| **Indexing** | `build . [--precise]`, `stale`, `stats` | Parse AST, write graph. Check freshness. Index health. |
| **Navigation** | `query`, `callers [--depth N]`, `callees [--depth N]`, `path`, `source`, `node` | Find symbols, trace call chains, extract source. |
| **Context** | `context`, `explain`, `focus`, `endpoint` | Bundled structural data in one call. Token savers. |
| **Change Analysis** | `plan`, `review`, `risk`, `impact [--uncommitted\|--since]`, `changes [--git]`, `api --since` | Pre-edit planning, post-edit review, risk analysis, blast radius, drift. |
| **Architecture** | `boundaries`, `coupling`, `complexity`, `godobj`, `orphans`, `arity` | Quality gates, dead code, coupling, god objects. |
| **Types & Structs** | `fields`, `implementers [--test-only]`, `interfaces`, `embeds`, `constructors`, `literals`, `usages`, `mutate`, `schema` | Struct fields, interface satisfaction, type usage. |
| **Infrastructure** | `routes`, `sql`, `envs`, `errors`, `concurrency`, `globals`, `deps [--transitive]`, `dependents` | HTTP routes, SQL, env vars, concurrency, imports. |
| **Testing** | `tests`, `fixtures`, `mocks` | Test coverage map, helpers, mock implementations. |
| **Error Tracing** | `errorflow [--no-tests]`, `trace` | Reverse-BFS from error strings to HTTP entry points. |
| **Diagnostics** | `hotspot`, `returnusage`, `skeleton`, `diagram`, `changes`, `public` | Hotspots, return usage, API signatures, Mermaid diagrams. |
| **CI/CD** | `check [--since\|--uncommitted]`, `gate`, `snapshot save\|diff\|list\|drop` | Policy checks, threshold enforcement, metric snapshots. |
| **Telemetry** | `session create\|end\|audit\|cleanup` | Agent compliance tracking and grading (A–F). |
| **LLM-Wiki** | `wiki [--output dir]` | Generate `llm-wiki/` — machine-first markdown pages for zero-cost agent orientation (overview, architecture, hotspots, routes, env, errors, concurrency, per-package, API surface). |
| **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. |
| **Untested** | `untested [--pkg name] [--top N] [--json]` | Functions with callers but zero test edges — coverage gaps invisible to orphans or per-symbol test queries. One sweep replaces N `tests ` calls. |
| **Doc** | `doc [--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. |
> Full command reference with examples: [gograph.identuum.ai/docs/command-reference](https://gograph.identuum.ai/docs/command-reference/)
Architecture Boundary Enforcement
Define boundaries in `.gograph/boundaries.json`:
```json
{
"layers": [
{ "name": "domain", "packages": ["internal/domain/**"], "may_import": [] },
{ "name": "handler", "packages": ["internal/handler/**"], "may_import": ["internal/service/**", "internal/domain/**"] }
]
}
```
Run `gograph boundaries` — exits with code 1 on violation. Works in CI/CD.
## AI Agent Integration
**One-command setup** (Claude Desktop + Claude Code):
```bash
gograph add-claude-plugin
```
This registers the MCP server, injects `CLAUDE.md` steering rules, and installs a `PreToolUse` hook that redirects `grep` on Go symbols to `gograph` tools.
**Other agents** (Cursor, Copilot, Antigravity, etc.):
```bash
gograph mcp . # Run as MCP server over stdio
```
Add to your `.cursorrules` or AI system prompt:
> Before answering architecture or repository questions, inspect the available `gograph_*` MCP tools and use them instead of grep/find. Run `gograph capabilities` first.
All commands support `--json` for machine-readable output:
```bash
gograph callers "ValidateToken" --json
# → {"schema_version": "1", "command": "callers", "status": "ok", "count": 2, "results": [...]}
```
For full integration guides, see [docs/coding-agent-usage.md](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:
```bash
gograph build . --precise
gograph wiki # writes to ./llm-wiki/
# then read: llm-wiki/README.md → project.md → rules.md → agent-contract.md → overview.md
```
Add `llm-wiki/` to `.gitignore` — these files are regenerated each session.
## 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 |
|--------|---------|
| `github.com/gin-gonic/gin` | `v1.9.1` |
| `github.com/jackc/pgx/v5` | `v5.5.5` |
**Important Symbols (Top by outgoing calls)**
| Symbol | Kind | File | Line | Calls out |
|--------|------|------|------|-----------|
| `(Server).Start` | method | `server.go` | 42 | 18 |
| `ValidateAuth` | function | `auth.go` | 12 | 14 |
---
## Why not use a Language Server (`gopls`)?
`gopls` is optimized for human IDEs. `gograph` is optimized for terminal-based LLMs:
1. **Protocol Mismatch** — `gopls` returns `file:line:col` coordinates. Agents must then burn tokens running `cat`/`sed` to read the actual code. `gograph` extracts the exact structural slice and formats it as Markdown.
2. **Graph-Level Diagnostics** — `gopls` does hover and go-to-definition. `gograph` does reverse-BFS error tracing, full blast radius analysis, and PR-level change plans across the entire call graph.
3. **Composable Intelligence** — `gopls` answers one question at a time. `gograph context` bundles node + source + callers + callees + tests in a single call. `gograph plan` aggregates impact, routes, SQL, env, and test risk into one checklist.
Correctness model
- **Default mode** uses Go AST parsing and best-effort heuristics. Tolerates incomplete or non-compiling repositories.
- **Precise mode** uses type-checked enrichment and requires compilable packages.
- Heuristic extractors (routes, SQL, tests, error mapping) are navigation aids, not authoritative program analysis.
Non-goals
- No multi-language parsing
- No AI/model API calls
- No embeddings or SaaS backend
- No telemetry
- No replacement for compiler/type-checker correctness
## Contributing
Pull requests welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for build, test, and contribution guidelines.
> **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.
## License
MIT — see [LICENSE](LICENSE).
[](https://glama.ai/mcp/servers/ozgurcd/gograph)