{"id":49720630,"url":"https://github.com/ozgurcd/gograph","last_synced_at":"2026-06-14T23:05:06.338Z","repository":{"id":356629932,"uuid":"1233398203","full_name":"ozgurcd/gograph","owner":"ozgurcd","description":"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.","archived":false,"fork":false,"pushed_at":"2026-06-10T03:44:46.000Z","size":40282,"stargazers_count":170,"open_issues_count":0,"forks_count":12,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-10T05:20:33.580Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://github.com/ozgurcd/gograph","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ozgurcd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-08T23:15:18.000Z","updated_at":"2026-06-10T03:44:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ozgurcd/gograph","commit_stats":null,"previous_names":["ozgurcd/gograph"],"tags_count":94,"template":false,"template_full_name":null,"purl":"pkg:github/ozgurcd/gograph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozgurcd%2Fgograph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozgurcd%2Fgograph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozgurcd%2Fgograph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozgurcd%2Fgograph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ozgurcd","download_url":"https://codeload.github.com/ozgurcd/gograph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozgurcd%2Fgograph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34340819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-05-09T01:13:59.123Z","updated_at":"2026-06-14T23:05:06.333Z","avatar_url":"https://github.com/ozgurcd.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gograph\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/ozgurcd/gograph)](https://goreportcard.com/report/github.com/ozgurcd/gograph)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/ozgurcd/gograph)](https://github.com/ozgurcd/gograph)\n[![Homebrew](https://img.shields.io/badge/homebrew-available-orange)](https://github.com/ozgurcd/homebrew-tap)\n[![Docs](https://img.shields.io/badge/docs-gograph.identuum.ai-blue)](https://gograph.identuum.ai)\n\n**Stop burning tokens on `grep`. Give your AI agent a graph.**\n\n`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.\n\n![Gograph Demo](gograph-demo.gif)\n\n\u003e **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.\n\n## Quick Start\n\n```bash\n# Install\nbrew install ozgurcd/tap/gograph\n\n# Build the graph\ngograph build . --precise\n\n# Try it — who calls ValidateToken?\ngograph callers \"ValidateToken\"\n\n# Full context in ONE call (node + source + callers + callees + tests)\ngograph context \"ValidateToken\"\n\n# Change plan before editing (callers, tests, routes, SQL, env risk)\ngograph plan \"ValidateToken\"\n```\n\n## Why gograph?\n\n*Benchmarked on gograph's own codebase (70 files, 518 symbols, 16 packages):*\n| Task | `grep -rn` | `gograph` | Savings |\n|---|---|---|---|\n| Find callers of `loadGraph` | 158 noisy lines (comments, docs, vars) | 56 exact structural call sites | ~65% noise eliminated |\n| Locate symbol definitions | 842 lines matching \"Symbol\" | 83 true type/method declarations | ~90% noise eliminated |\n| Read one function body | `cat` dumps 180+ lines of the whole file | `source` extracts the exact 12-line function | ~93% fewer tokens |\n| Understand a symbol fully | 4–5 separate tool calls | 1 call: `context` bundles everything | 80% fewer tool calls |\n\n## Key Features\n\n**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/)\n\n**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`\n\n**Token-Saving Composites** — `context` replaces 5 calls. `plan` replaces 8. `explain` synthesizes architectural narratives. Built to minimize agent round-trips.\n\n**Safe by Design** — no network, no code execution, no secrets, no `.env` files read. AI worktree directories (`.claude/`, `.cursor/`, `.agents/`) auto-excluded.\n\n**Architecture Enforcement** — boundary rules, API drift detection, complexity gates, dead code sweeps, god-object detection, coupling analysis. Run in CI with `gograph gate`.\n\n**Agent Compliance Auditing** — session telemetry tracks whether agents run `plan` before edits and `review` after. Grades agent behavior A–F with actionable recommendations.\n\n## Command Reference\n\nAll commands support `--json` for machine-readable output and `--files-only` for flat file lists.\n\n| Category | Commands | What it does |\n|---|---|---|\n| **Indexing** | `build . [--precise]`, `stale`, `stats` | Parse AST, write graph. Check freshness. Index health. |\n| **Navigation** | `query`, `callers [--depth N]`, `callees [--depth N]`, `path`, `source`, `node` | Find symbols, trace call chains, extract source. |\n| **Context** | `context`, `explain`, `focus`, `endpoint` | Bundled structural data in one call. Token savers. |\n| **Change Analysis** | `plan`, `review`, `risk`, `impact [--uncommitted\\|--since]`, `changes [--git]`, `api --since` | Pre-edit planning, post-edit review, risk analysis, blast radius, drift. |\n| **Architecture** | `boundaries`, `coupling`, `complexity`, `godobj`, `orphans`, `arity` | Quality gates, dead code, coupling, god objects. |\n| **Types \u0026 Structs** | `fields`, `implementers [--test-only]`, `interfaces`, `embeds`, `constructors`, `literals`, `usages`, `mutate`, `schema` | Struct fields, interface satisfaction, type usage. |\n| **Infrastructure** | `routes`, `sql`, `envs`, `errors`, `concurrency`, `globals`, `deps [--transitive]`, `dependents` | HTTP routes, SQL, env vars, concurrency, imports. |\n| **Testing** | `tests`, `fixtures`, `mocks` | Test coverage map, helpers, mock implementations. |\n| **Error Tracing** | `errorflow [--no-tests]`, `trace` | Reverse-BFS from error strings to HTTP entry points. |\n| **Diagnostics** | `hotspot`, `returnusage`, `skeleton`, `diagram`, `changes`, `public` | Hotspots, return usage, API signatures, Mermaid diagrams. |\n| **CI/CD** | `check [--since\\|--uncommitted]`, `gate`, `snapshot save\\|diff\\|list\\|drop` | Policy checks, threshold enforcement, metric snapshots. |\n| **Telemetry** | `session create\\|end\\|audit\\|cleanup` | Agent compliance tracking and grading (A–F). |\n| **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). |\n| **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. |\n| **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 \u003csym\u003e` calls. |\n| **Doc** | `doc \u003cpkg[.Symbol]\u003e [--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. |\n\n\u003e Full command reference with examples: [gograph.identuum.ai/docs/command-reference](https://gograph.identuum.ai/docs/command-reference/)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eArchitecture Boundary Enforcement\u003c/strong\u003e\u003c/summary\u003e\n\nDefine boundaries in `.gograph/boundaries.json`:\n```json\n{\n  \"layers\": [\n    { \"name\": \"domain\", \"packages\": [\"internal/domain/**\"], \"may_import\": [] },\n    { \"name\": \"handler\", \"packages\": [\"internal/handler/**\"], \"may_import\": [\"internal/service/**\", \"internal/domain/**\"] }\n  ]\n}\n```\nRun `gograph boundaries` — exits with code 1 on violation. Works in CI/CD.\n\u003c/details\u003e\n\n## AI Agent Integration\n\n**One-command setup** (Claude Desktop + Claude Code):\n```bash\ngograph add-claude-plugin\n```\nThis registers the MCP server, injects `CLAUDE.md` steering rules, and installs a `PreToolUse` hook that redirects `grep` on Go symbols to `gograph` tools.\n\n**Other agents** (Cursor, Copilot, Antigravity, etc.):\n```bash\ngograph mcp .   # Run as MCP server over stdio\n```\nAdd to your `.cursorrules` or AI system prompt:\n\u003e Before answering architecture or repository questions, inspect the available `gograph_*` MCP tools and use them instead of grep/find. Run `gograph capabilities` first.\n\nAll commands support `--json` for machine-readable output:\n```bash\ngograph callers \"ValidateToken\" --json\n# → {\"schema_version\": \"1\", \"command\": \"callers\", \"status\": \"ok\", \"count\": 2, \"results\": [...]}\n```\n\nFor full integration guides, see [docs/coding-agent-usage.md](docs/coding-agent-usage.md).\n\n**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:\n```bash\ngograph build . --precise\ngograph wiki                 # writes to ./llm-wiki/\n# then read: llm-wiki/README.md → project.md → rules.md → agent-contract.md → overview.md\n```\nAdd `llm-wiki/` to `.gitignore` — these files are regenerated each session.\n\n## Example Output\n\nWhen you run `gograph build .`, the generated `GRAPH_REPORT.md` gives your AI a condensed context map:\n\n**External Dependencies (Tech Stack)**\n| Module | Version |\n|--------|---------|\n| `github.com/gin-gonic/gin` | `v1.9.1` |\n| `github.com/jackc/pgx/v5` | `v5.5.5` |\n\n**Important Symbols (Top by outgoing calls)**\n| Symbol | Kind | File | Line | Calls out |\n|--------|------|------|------|-----------|\n| `(Server).Start` | method | `server.go` | 42 | 18 |\n| `ValidateAuth` | function | `auth.go` | 12 | 14 |\n\n---\n\n## Why not use a Language Server (`gopls`)?\n\n`gopls` is optimized for human IDEs. `gograph` is optimized for terminal-based LLMs:\n\n1. **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.\n2. **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.\n3. **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.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCorrectness model\u003c/strong\u003e\u003c/summary\u003e\n\n- **Default mode** uses Go AST parsing and best-effort heuristics. Tolerates incomplete or non-compiling repositories.\n- **Precise mode** uses type-checked enrichment and requires compilable packages.\n- Heuristic extractors (routes, SQL, tests, error mapping) are navigation aids, not authoritative program analysis.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eNon-goals\u003c/strong\u003e\u003c/summary\u003e\n\n- No multi-language parsing\n- No AI/model API calls\n- No embeddings or SaaS backend\n- No telemetry\n- No replacement for compiler/type-checker correctness\n\u003c/details\u003e\n\n## Contributing\n\nPull requests welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for build, test, and contribution guidelines.\n\n\u003e **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.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n[![gograph MCP server](https://glama.ai/mcp/servers/ozgurcd/gograph/badges/score.svg)](https://glama.ai/mcp/servers/ozgurcd/gograph)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fozgurcd%2Fgograph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fozgurcd%2Fgograph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fozgurcd%2Fgograph/lists"}