[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-76150":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":41,"readmeContent":42,"aiSummary":43,"trendingCount":15,"starSnapshotCount":15,"syncStatus":44,"lastSyncTime":45,"discoverSource":46},76150,"gograph","ozgurcd\u002Fgograph","ozgurcd","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:\u002F\u002Fgithub.com\u002Fozgurcd\u002Fgograph",null,"Go",171,12,1,0,8,18,43,24,3.34,"MIT License",false,"master",true,[26,27,28,29,30,31,32,33,34,35,36,37,38,39,40],"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","2026-06-12 02:03:40","# gograph\n\n[![Go Report Card](https:\u002F\u002Fgoreportcard.com\u002Fbadge\u002Fgithub.com\u002Fozgurcd\u002Fgograph)](https:\u002F\u002Fgoreportcard.com\u002Freport\u002Fgithub.com\u002Fozgurcd\u002Fgograph)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n\n`gograph` is a local AST\u002Ftype-aware Go repository context indexer for AI coding agents.\n\n![Gograph Demo](gograph-demo.gif)\n\nIt builds a compact graph of packages, symbols, calls, routes, config reads, tests, and code-quality signals so agents can navigate Go repositories with fewer raw file reads.\n\n> **Note on Language Support:** I originally built `gograph` specifically for **Golang** because that is what I needed for my own workflows. It currently only parses and maps Go codebases. However, the architecture is extensible! If you want to add support for other languages (Python, TypeScript, Rust, etc.), **contributions are more than welcome.** Please see the [Contributing Guide](CONTRIBUTING.md) to get started.\n\n## Why not use a Language Server (`gopls`)?\n\nWhile `gopls` has access to similar AST and type data, connecting an AI coding agent to a Language Server is notoriously difficult and inefficient:\n\n1. **Protocol Mismatch:** AI agents operate inside terminal environments. `gopls` communicates via JSON-RPC over `stdin\u002Fstdout`. While you can invoke some `gopls` CLI commands, it usually returns raw file coordinates (`file:line:col`). This forces the agent to burn tokens running `cat` or `sed` to actually read the referenced code.\n2. **LLM-Optimized Output:** `gograph` doesn't just find coordinates; it physically extracts the exact structural slice (the struct body, the interface, the method) and formats it natively in Markdown. The AI reads exactly what it needs in one shot with zero surrounding file noise.\n3. **Graph-Level Diagnostics:** Language servers are built for point-in-time human IDE features (like hover or go-to-definition). `gograph` is built for systemic graph traversal. For example, `gograph trace \"parse failed\"` performs a reverse-BFS from an error string all the way up the call stack to the HTTP entry point. `gograph impact` calculates the full blast radius of a code change. `gopls` doesn't natively perform graph-traversal diagnostics like this out of the box.\n\nIn short: `gopls` is optimized for human IDEs. `gograph` is optimized for terminal-based LLMs trying to save context tokens.\n\n## Features\n- **Local Only:** Graph building performs no network calls and sends no source code to external APIs. MCP integration is local stdio-based.\n- **Go Focused:** Maps Go project structures, packages, and dependencies using the standard AST.\n- **Targeted Focus:** Extract incredibly targeted context for a single package using `focus` to save LLM tokens.\n- **Token-Saving Context Bundle:** `context \u003Csymbol>` replaces 4–5 separate tool calls — returns node, source, callers, callees, and tests in one response.\n- **Hotspot Ranking:** `hotspot` ranks functions by incoming call count so agents know which functions to study first.\n- **Code Quality Analysis:** Cyclomatic complexity (`complexity`), god-object detection (`godobj`), and package coupling\u002Finstability (`coupling`).\n- **Change Detection:** `changes` surfaces new\u002Fmodified\u002Fdeleted symbols since the last build without re-reading source files.\n- **Dependency Trees:** `deps \u003Cpkg> [--transitive]` shows direct or full transitive import closures for any package.\n- **Tech Stack Extraction:** Automatically parses `go.mod` to summarize your external dependencies (like `gin` or `pgx`) so agents instantly understand your stack.\n- **Concurrency Mapping:** Detects goroutine spawns, channel sends, mutex locks, WaitGroup usage, and `sync.Once.Do` calls across the entire codebase.\n- **Interface Satisfaction:** Best-effort duck-typing analysis that tells you which interfaces any struct satisfies — without running the compiler.\n- **Test Coverage Map:** Best-effort mapping that links `Test*` functions to the production symbols they likely exercise.\n- **Environment Config:** Surfaces every `os.Getenv` \u002F `viper.Get*` read with file, line, and enclosing function.\n- **Pathfinding:** `path \u003Cfrom> \u003Cto>` finds the shortest call chain between any two symbols via BFS.\n- **Dead Code Detection:** `orphans` uses full reachability analysis from entry points — stricter than simple 0-call-count checks.\n- **Clean Graph (No Generated Files):** Uses strict line-based detection to automatically exclude generated files like mocks or protobufs.\n- **Fast:** Written in Go for high performance.\n\n## Non-goals\n- No multi-language parsing.\n- No AI\u002Fmodel API calls.\n- No embeddings.\n- No SaaS backend.\n- No telemetry.\n- No replacement for compiler\u002Ftype-checker correctness.\n- No guarantee that heuristic extractors find every route, SQL query, test relation, or dynamic call.\n\n## Correctness model\n- **Default mode** uses Go AST parsing and best-effort heuristics. It tolerates incomplete or non-compiling repositories.\n- **Precise mode** uses type-checked enrichment and requires compilable packages.\n- Heuristic extractors such as routes, SQL, tests, and error mapping are navigation aids, not authoritative program analysis.\n\n## Installation\n\n```bash\n# MacOS \u002F Linux (via Homebrew)\nbrew install ozgurcd\u002Ftap\u002Fgograph\n\n# Or using Go:\ngo install github.com\u002Fozgurcd\u002Fgograph\u002Fcmd\u002Fgograph@latest\n```\n\n## Usage\n\n**1. Generate the Graph (Run this after every major code change):**\n```bash\ngograph build .\n# OR for more precise type-checked analysis (slower, but provides exact dynamic dispatch & interface satisfaction proofs):\ngograph build . --precise\n```\n*This instantly generates `.gograph\u002Fgraph.json` and `.gograph\u002FGRAPH_REPORT.md`.*\n\n**2. Query the Graph (Lightning fast, no re-parsing):**\n```bash\ngograph boundaries [--config]     # Verify package architecture constraints using boundaries.json\ngograph callees \"InitServer\"      # See what InitServer calls (with exact source snippet)\ngograph callers \"ValidateToken\"   # See what functions call ValidateToken (with exact source snippet)\ngograph complexity                # Cyclomatic complexity for all functions (highest first)\ngograph complexity \"Run\"          # Complexity for a specific function\ngograph concurrency               # Map all goroutines, channels, mutexes, and sync primitives\ngograph coupling                  # Package fan-in, fan-out, instability table\ngograph coupling \"internal\u002Fauth\"  # Filter to a specific package\ngograph embeds \"Mutex\"            # See which structs embed a target struct\ngograph envs                      # List every environment variable read in the codebase\ngograph errors                    # Map every custom error and panic to its function\ngograph fields \"User\"             # Extract all fields and types of a struct\ngograph focus \"internal\u002Fauth\"     # Generate a highly targeted context for one package\ngograph godobj                    # Find god-object struct candidates\ngograph godobj --methods 10 --fields 12 --calls 30 --top 5  # Custom thresholds\ngograph impact \"ValidateToken\"    # View the full blast radius (all downstream callers)\ngograph impact --uncommitted      # Calculate the blast radius of all your uncommitted code changes\ngograph implementers \"AuthService\" # See which structs implement an interface\ngograph imports \"redis\"           # Find all files that import a specific external package\ngograph interfaces \"UserService\"  # See which interfaces a struct satisfies (type-checked if --precise was used)\ngograph node \"UserStruct\"         # Get detailed AST info about a specific node\ngograph orphans                   # List functions and methods with 0 explicit incoming calls (dead code)\ngograph path \"CreateUser\" \"sql\"   # Shortest call chain between two symbols\ngograph public \"internal\u002Fauth\"    # Filter graph to only show exported public symbols\ngograph query \"Auth\"              # Search for symbols, files, or packages\ngograph routes                    # Extract all HTTP REST API routes (e.g. GET \u002Fapi)\ngograph endpoint \"CreateUser\"     # Full vertical slice: handler → call chain → SQL → env reads (PREFERRED: use handler name)\ngograph endpoint \"POST \u002Fapi\u002Fusers\" # Same but via route pattern (ONLY works for flat routers — fails with Gin\u002FEcho\u002FChi groups)\ngograph source \"ValidateToken\"    # Extract the source code for a specific symbol\ngograph sql                       # Extract database SQL queries from the AST\ngograph stale                     # Check if graph.json is out of date vs source files\ngograph tests \"ValidateToken\"     # Find which test functions exercise a named symbol\n# --- STATIC GUARDS & CI ENFORCEMENT ---\ngograph check                     # Run static policy checks using .gograph\u002Fchecks.json\ngograph check --uncommitted       # Run checks, including uncommitted code\ngograph check --since main        # Run checks, including API drift against main\ngograph boundaries                # Verify package architecture constraints against boundaries.json\ngograph gate                      # Fail CI if any .gograph.yml threshold is violated (complexity, instability, orphans, coupling)\n# --- SNAPSHOTS ---\ngograph snapshot save v1          # Capture current architectural metrics under label v1\ngograph snapshot diff v1          # Compare current graph against snapshot v1\ngograph snapshot list             # List all saved snapshots\ngograph snapshot drop v1          # Delete snapshot v1\n# --- TOKEN SAVERS ---\ngograph api --since main          # Identify breaking API and contract changes since a git reference\ngograph arity --min 5             # Find functions with many arguments (long parameter list smell)\ngograph changes                   # New\u002Fmodified\u002Fdeleted symbols since last build\ngograph constructors \"User\"       # Find factory functions returning the named struct\ngograph context \"ValidateToken\"   # Node + source + callers + callees + tests in ONE call\ngograph explain \"ValidateToken\"   # LLM-ready architectural narrative: role, callers, callees, complexity, SQL, env, tests\ngograph deps \"internal\u002Fauth\"      # Direct import dependencies of a package\ngograph deps \"internal\u002Fauth\" --transitive  # Full transitive closure\ngograph fixtures \"internal\u002Fauth\"  # Find test helper structs and functions in test files\ngograph globals \"internal\u002Fauth\"   # Find pkg-level vars, consts, and functions mutating them\ngograph hotspot                   # Top 10 most-called functions (where to focus first)\ngograph hotspot --top 20          # Expand to top 20\ngograph mocks \"AuthService\"       # Find structs implementing an interface in test\u002Fmock files\ngograph mutate \"User.Status\"      # Find functions that mutate a specific struct field\ngograph plan \"ValidateToken\"      # Generate an operational change plan (callers, tests, risk profile) before editing a symbol\ngograph plan --uncommitted        # Generate a change plan for all currently uncommitted modified symbols\ngograph review \"ValidateToken\"    # Generate a post-edit final review report for a modified symbol\ngograph review --uncommitted      # Generate a post-edit final review report for all uncommitted changes\ngograph schema \"users\"            # Find structs mapped to a database table\u002Fschema via tags\ngograph skeleton                  # Output the whole repository's API signatures (bodies stripped)\ngograph trace \"parse failed\"      # Trace an error string backwards to entry points\ngograph errorflow \"invalid token\" # Trace an error's path from definition up to HTTP handlers (heuristic, NO SSA)\n# endpoint: full vertical slice for one HTTP endpoint. IMPORTANT: route patterns only work with flat routers.\n# With Gin\u002FEcho\u002FChi Group() routing, the prefix is lost in the AST. Use handler symbol name instead.\ngograph endpoint \"CreateUser\"     # RECOMMENDED: always works regardless of routing style [--depth N] [--json]\ngograph endpoint \"POST \u002Fapi\u002Fusers\" # route pattern: only works if path is a flat string literal (no Group() prefix)\n\n**3. Architecture Boundary Enforcement:**\nYou can configure `gograph` to actively enforce clean architecture by defining boundaries. Create a `.gograph\u002Fboundaries.json` file in your root directory:\n```json\n{\n  \"layers\": [\n    {\n      \"name\": \"domain\",\n      \"packages\": [\"internal\u002Fdomain\u002F**\"],\n      \"may_import\": []\n    },\n    {\n      \"name\": \"handler\",\n      \"packages\": [\"internal\u002Fhandler\u002F**\"],\n      \"may_import\": [\n        \"internal\u002Fservice\u002F**\",\n        \"internal\u002Fdomain\u002F**\"\n      ]\n    }\n  ]\n}\n```\n*Note: Standard library imports are implicitly allowed. Imports within the same layer are also implicitly allowed.*\n\nRun the enforcement check:\n```bash\ngograph boundaries\n```\n*If a violation is found (e.g., `handler` imports `internal\u002Frepository` directly), it will exit with code 1 and print the exact file that violated the rule. Extremely useful for CI\u002FCD or Agent `CLAUDE.md` instructions!*\n\n**4. Agent JSON Integration:**\nAll search and query commands support the `--json` flag to emit strictly formatted, machine-parseable JSON envelopes.\n\nFor specific instructions on how to configure agents to use `gograph`, read the [Claude Code Integration Guide](docs\u002Fclaude-code-integration.md).\n\n```bash\ngograph callers \"ValidateToken\" --json\n```\n*Returns: `{\"schema_version\": \"1\", \"command\": \"callers\", \"status\": \"ok\", \"count\": 2, \"results\": [...]}`*\n\n\n**5. Run as an MCP Server (For AI Agents):**\nIf you want to give your AI agent native tool execution capabilities, `gograph` has a built-in [Model Context Protocol (MCP)](https:\u002F\u002Fmodelcontextprotocol.io\u002F) server.\n\nTo install the plugin automatically on macOS, Windows, or Linux, run:\n```bash\ngograph add-claude-plugin\n```\n\nThis single command does three things:\n1. **Registers the MCP server** in `claude_desktop_config.json` (Claude Desktop) so `gograph` tools are available to Claude natively.\n2. **Injects steering rules** into `~\u002F.claude\u002FCLAUDE.md` — Claude reads this automatically and knows to use `gograph_query` instead of `grep` for Go symbol searches.\n3. **Installs a smart `PreToolUse` hook** at `~\u002F.claude\u002Fhooks\u002Fgograph-guard.sh` — this intercepts `grep`\u002F`rg` calls targeting Go symbols and redirects Claude to the appropriate `gograph` MCP tool, saving tokens and improving precision.\n\nThe hook is **smart**: it only blocks grep when the search pattern looks like a Go identifier (PascalCase\u002FcamelCase, 3+ chars). Legitimate raw-text searches in YAML, Markdown, SQL, or comment files are allowed through unchanged.\n\nFor Claude Code (CLI) users, also run:\n```bash\nclaude mcp add gograph -- gograph mcp .\n```\n\nYou can also run the MCP server manually over stdio:\n```bash\ngograph mcp .\n```\n\n## 🤖 Integrating with AI Agents (Cursor, Claude Code, Copilot)\n\nTo get the best results from your AI coding assistant, run `gograph add-claude-plugin`. It automatically configures everything:\n- MCP server registration for native tool access\n- `CLAUDE.md` rules that steer Claude to use `gograph` instead of `grep`\n- A `PreToolUse` hook that enforces Go symbol lookups go through `gograph`\n\nIf you prefer manual setup, add this to your `.cursorrules`, `CLAUDE.md`, or AI system instructions:\n\n> **System Prompt:**\n> Before answering architecture or repository questions, inspect the available `gograph_*` MCP tools for the current project and use them instead of grep\u002Ffind. Each project ships its own gograph MCP server; pick the matching one. If using the CLI directly, run `gograph capabilities` first.\n\n## Example Output\n\nWhen you run `gograph build .`, the generated `GRAPH_REPORT.md` gives your AI a condensed, highly-dense context map that looks like this:\n\n**External Dependencies (Tech Stack)**\n| Module | Version |\n|--------|---------|\n| `github.com\u002Fgin-gonic\u002Fgin` | `v1.9.1` |\n| `github.com\u002Fjackc\u002Fpgx\u002Fv5` | `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## Contributing\n\nWe love pull requests! See the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines on how to build, test, and contribute to the project. If you are adding support for a new language, please open an issue first to discuss the design.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","`gograph` 是一个专为 Go 代码库设计的本地命令行工具，用于生成仓库结构并提高IDE上下文感知能力。其核心功能包括通过构建紧凑的包、符号、调用、路由等图谱来帮助AI编码代理更高效地导航Go代码库，同时减少对原始文件的读取次数。技术特点上，`gograph` 采用Go语言编写，专注于Go项目的映射与依赖解析，并且完全在本地运行，不涉及任何网络请求或外部API调用，从而确保了数据的安全性和隐私性。此外，它还提供了如聚焦特定包以节省LLM令牌、一键获取符号上下文信息等功能，非常适合需要在终端环境中使用AI辅助进行Go项目开发和维护的场景。",2,"2026-06-11 03:54:39","CREATED_QUERY"]