In short: gopls is optimized for human IDEs. gograph is optimized for terminal-based LLMs trying to save context tokens.

Features

• Local Only: Graph building performs no network calls and sends no source code to external APIs. MCP integration is local stdio-based.
• Go Focused: Maps Go project structures, packages, and dependencies using the standard AST.
• Targeted Focus: Extract incredibly targeted context for a single package using focus to save LLM tokens.
• Token-Saving Context Bundle: context <symbol> replaces 4–5 separate tool calls — returns node, source, callers, callees, and tests in one response.
• Hotspot Ranking: hotspot ranks functions by incoming call count so agents know which functions to study first.
• Code Quality Analysis: Cyclomatic complexity (complexity), god-object detection (godobj), and package coupling/instability (coupling).
• Change Detection: changes surfaces new/modified/deleted symbols since the last build without re-reading source files.
• Dependency Trees: deps <pkg> [--transitive] shows direct or full transitive import closures for any package.
• Tech Stack Extraction: Automatically parses go.mod to summarize your external dependencies (like gin or pgx) so agents instantly understand your stack.
• Concurrency Mapping: Detects goroutine spawns, channel sends, mutex locks, WaitGroup usage, and sync.Once.Do calls across the entire codebase.
• Interface Satisfaction: Best-effort duck-typing analysis that tells you which interfaces any struct satisfies — without running the compiler.
• Test Coverage Map: Best-effort mapping that links Test* functions to the production symbols they likely exercise.
• Environment Config: Surfaces every os.Getenv / viper.Get* read with file, line, and enclosing function.
• Pathfinding: path <from> <to> finds the shortest call chain between any two symbols via BFS.
• Dead Code Detection: orphans uses full reachability analysis from entry points — stricter than simple 0-call-count checks.
• Clean Graph (No Generated Files): Uses strict line-based detection to automatically exclude generated files like mocks or protobufs.
• Fast: Written in Go for high performance.

Non-goals

• No multi-language parsing.
• No AI/model API calls.
• No embeddings.
• No SaaS backend.
• No telemetry.
• No replacement for compiler/type-checker correctness.
• No guarantee that heuristic extractors find every route, SQL query, test relation, or dynamic call.

Correctness model

• Default mode uses Go AST parsing and best-effort heuristics. It tolerates incomplete or non-compiling repositories.
• Precise mode uses type-checked enrichment and requires compilable packages.
• Heuristic extractors such as routes, SQL, tests, and error mapping are navigation aids, not authoritative program analysis.

Installation

# MacOS / Linux (via Homebrew)
brew install ozgurcd/tap/gograph

# Or using Go:
go install github.com/ozgurcd/gograph/cmd/gograph@latest

Usage

1. Generate the Graph (Run this after every major code change):

gograph build .
# OR for more precise type-checked analysis (slower, but provides exact dynamic dispatch & interface satisfaction proofs):
gograph build . --precise

This instantly generates .gograph/graph.json and .gograph/GRAPH_REPORT.md.

2. Query the Graph (Lightning fast, no re-parsing):

gograph boundaries [--config]     # Verify package architecture constraints using boundaries.json
gograph callees "InitServer"      # See what InitServer calls (with exact source snippet)
gograph callers "ValidateToken"   # See what functions call ValidateToken (with exact source snippet)
gograph complexity                # Cyclomatic complexity for all functions (highest first)
gograph complexity "Run"          # Complexity for a specific function
gograph concurrency               # Map all goroutines, channels, mutexes, and sync primitives
gograph coupling                  # Package fan-in, fan-out, instability table
gograph coupling "internal/auth"  # Filter to a specific package
gograph embeds "Mutex"            # See which structs embed a target struct
gograph envs                      # List every environment variable read in the codebase
gograph errors                    # Map every custom error and panic to its function
gograph fields "User"             # Extract all fields and types of a struct
gograph focus "internal/auth"     # Generate a highly targeted context for one package
gograph godobj                    # Find god-object struct candidates
gograph godobj --methods 10 --fields 12 --calls 30 --top 5  # Custom thresholds
gograph impact "ValidateToken"    # View the full blast radius (all downstream callers)
gograph impact --uncommitted      # Calculate the blast radius of all your uncommitted code changes
gograph implementers "AuthService" # See which structs implement an interface
gograph imports "redis"           # Find all files that import a specific external package
gograph interfaces "UserService"  # See which interfaces a struct satisfies (type-checked if --precise was used)
gograph node "UserStruct"         # Get detailed AST info about a specific node
gograph orphans                   # List functions and methods with 0 explicit incoming calls (dead code)
gograph path "CreateUser" "sql"   # Shortest call chain between two symbols
gograph public "internal/auth"    # Filter graph to only show exported public symbols
gograph query "Auth"              # Search for symbols, files, or packages
gograph routes                    # Extract all HTTP REST API routes (e.g. GET /api)
gograph source "ValidateToken"    # Extract the source code for a specific symbol
gograph sql                       # Extract database SQL queries from the AST
gograph stale                     # Check if graph.json is out of date vs source files
gograph tests "ValidateToken"     # Find which test functions exercise a named symbol
# --- STATIC GUARDS ---
gograph check                     # Run static policy checks using .gograph/checks.json
gograph check --uncommitted       # Run checks, including uncommitted code
gograph check --since master      # Run checks, including API drift against master
# --- TOKEN SAVERS ---
gograph api --since master        # Identify breaking API and contract changes since a git reference
gograph arity --min 5             # Find functions with many arguments (long parameter list smell)
gograph changes                   # New/modified/deleted symbols since last build
gograph constructors "User"       # Find factory functions returning the named struct
gograph context "ValidateToken"   # Node + source + callers + callees + tests in ONE call
gograph deps "internal/auth"      # Direct import dependencies of a package
gograph deps "internal/auth" --transitive  # Full transitive closure
gograph fixtures "internal/auth"  # Find test helper structs and functions in test files
gograph globals "internal/auth"   # Find pkg-level vars, consts, and functions mutating them
gograph hotspot                   # Top 10 most-called functions (where to focus first)
gograph hotspot --top 20          # Expand to top 20
gograph mocks "AuthService"       # Find structs implementing an interface in test/mock files
gograph mutate "User.Status"      # Find functions that mutate a specific struct field
gograph plan "ValidateToken"      # Generate an operational change plan (callers, tests, risk profile) before editing a symbol
gograph plan --uncommitted        # Generate a change plan for all currently uncommitted modified symbols
gograph review "ValidateToken"    # Generate a post-edit fin