GoreGraph

GoreGraph is a local, deterministic code-intelligence CLI. It scans source code without executing it and creates evidence-backed project maps for developers and AI coding assistants.

It answers practical orientation questions: where a symbol is defined, what it calls, which HTTP route reaches it, which frontend API usage maps to a backend endpoint, and which tests or persistence boundaries are connected to it.

The tool is intentionally conservative:

• no AI calls
• no network access during scans or Git-update previews; only an explicit Git update command with --execute fetches origin
• no telemetry
• no project code execution
• no Git hooks
• no agent config writes
• no global project modifications
• writes scan output to goregraph-out/ and, when a workspace is detected, workspace metadata to .goregraph-workspace/
• may add generated GoreGraph output paths to the relevant .gitignore files

What GoreGraph does

• Indexes symbols, imports, calls, routes, tests, API clients, and persistence patterns from source code.
• Connects frontend API usage to backend routes and shows the surrounding implementation path.
• Builds a workspace map across repositories or services, including confidence, diagnostics, and source evidence.
• Produces human-readable reports, machine-readable JSON, and an offline workspace dashboard.

The workspace dashboard answers eight separate questions without mixing their evidence models: Architecture maps services, API Catalog inventories provider endpoints, Endpoints follows consumer-to-provider relationships, Feature Flow shows an implementation chain, Data Flow follows fields, Code Explorer inspects exact classes and symbols, Diagnostics explains uncertainty, and Coverage distinguishes indexing completeness from analyzer support. Source locations, linked tests, safe verification commands, and bounded impact summaries remain evidence-backed and local.

For command reference, see COMMANDS.md. The output contract is documented in docs/OUTPUTS.md and SCHEMA.md; future work is in ROADMAP.md. The monotonic regression workflow defines the frozen Golden comparison, full-run gates, and external G1 evidence handling.

Local 1.4.1 testing and rollback are documented in docs/LOCAL-1.4.1.md.

Installation

Source version: GoreGraph 1.4.1 with output Schema 3.

This checkout contains the local 1.4.1 candidate for testing. It has not been pushed or published by this implementation. Existing package-manager commands below install published builds, not this local candidate.

Version 1.4.1 adds scoped Git ignore rules, faster script analysis, cancellable builds with file/phase progress, input-aware updates, recoverable output publication, and explicit partial/stale health. The historical strict agent workflow remains the default; goregraph context . --query "<task>" --protocol adaptive-v2 enables bounded verification and fallback metadata. MCP uses the same opt-in via goregraph mcp --protocol adaptive-v2.

The 1.4.0 baseline introduced content-aware workspace updates. GitHub Releases provides checksummed archives for macOS, Linux, and Windows. Release publication updates Homebrew and, when configured, Scoop and Winget publication repositories. Winget availability still depends on Microsoft package acceptance.

Homebrew macOS/Linux

Recommended macOS/Linux installation:

brew install gorecodecom/tap/goregraph

This command works without a separate brew tap step. Homebrew discovers the GoreCode tap from the fully qualified formula name.

Optional two-step installation:

brew tap gorecodecom/tap
brew install goregraph

Verify the installed binary:

goregraph version

Upgrade an existing Homebrew installation:

brew update
brew upgrade goregraph

brew install goregraph installs a missing formula. Updating an already installed version is done with brew upgrade.

Scoop Windows

If Scoop is not installed, open a regular, non-administrative PowerShell and run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

For other bootstrap options, see the official Scoop installer documentation.

Then add the GoreCode bucket and install GoreGraph:

scoop bucket add gorecode https://github.com/gorecodecom/scoop-bucket
scoop install goregraph

Verify the installed binary:

goregraph version

Manual Install Windows

Download the Windows archive from the latest GitHub release:

goregraph_Windows_x86_64.zip

Extract the ZIP and run:

.\goregraph.exe version

For regular use, place goregraph.exe in a directory on your Windows PATH.

GitHub Releases

Prebuilt archives are published for macOS, Linux, and Windows:

https://github.com/gorecodecom/goregraph/releases

Each release includes checksums.txt.

Manual archive names:

goregraph_Darwin_arm64.tar.gz
goregraph_Darwin_x86_64.tar.gz
goregraph_Linux_arm64.tar.gz
goregraph_Linux_x86_64.tar.gz
goregraph_Windows_x86_64.zip

After extracting the archive, run:

./goregraph version

On Windows PowerShell:

.\goregraph.exe version

Build From Source

Requirements:

• Go 1.23 or newer

Build:

go build -o goregraph ./cmd/goregraph

Run:

./goregraph help

During development you can also run:

go run ./cmd/goregraph help

Install the local checkout as the goregraph command:

go install ./cmd/goregraph
goregraph version
goregraph scan .

On Windows, go install writes goregraph.exe to go env GOPATH + \bin. Make sure that directory is on PATH before running goregraph scan . from another project.

Winget

Future Windows install command after the package is accepted into microsoft/winget-pkgs:

winget install --id GoreCode.GoreGraph -e

Winget metadata is generated during releases. The command is not live until the Winget manifest PR is accepted by Microsoft.

Quick Start

Choose the integration depth and projection for the consumer that needs it:

Consumer	Integration depth	Build	Recommended input
Developer / reviewer	Full human exploration	goregraph build dashboard .	Human-readable files in goregraph-out/dashboard/
AI coding assistant	Bounded task context	goregraph build agent .	One Context Pack compiled from goregraph-out/agent/context-index.json
Human and AI	Both projections	goregraph build all .	Both surfaces from one shared extraction
GoreGraph internals	Canonical machine index	built automatically	Data in goregraph-out/index/; never add this tree directly to prompts

goregraph scan . remains a compatibility alias for goregraph build all .. A single-project build needs no workspace marker.

Project or workspace build?

Choose the command by scan scope, not only by output type:

Scope	Command	What is scanned	Dashboard output
Current project with workspace refresh	goregraph build dashboard .	Only the selected project; sibling projects are not scanned	Project reports in goregraph-out/dashboard/; a detected workspace overlay is refreshed from existing sibling indexes
Current project only	goregraph build dashboard . --no-workspace	Only the selected project	Project reports in goregraph-out/dashboard/; workspace discovery and reconciliation are skipped
Changed workspace projects	goregraph workspace update . --target dashboard	Every project is content-checked; only changed, new, or incomplete projects are scanned	Updated project reports plus one reconciled interactive workspace dashboard
Complete workspace	goregraph workspace build dashboard .	Every discovered workspace project	Project reports plus the interactive dashboard in .goregraph-workspace/dashboard/

A project dashboard consists of human-readable reports. The full interactive Code Explorer and cross-service dashboard belong to the workspace dashboard. The same scan scopes apply when dashboard is replaced with agent or all. all creates agent and dashboard projections from one source extraction.

For human exploration:

goregraph workspace build dashboard .
goregraph dashboard .
goregraph dashboard open .

path prints and open opens the generated static dashboard. That export is offline and read-only; neither command starts a server. To organize the Architecture view, run the local editor explicitly:

goregraph workspace dashboard path . and goregraph workspace dashboard open . remain the explicit workspace-only compatibility forms for scripts that require workspace-only resolution.

goregraph dashboard edit .

The static dashboard's Edit layout button shows the same command, so the editing workflow remains discoverable without starting a server automatically. Only edit starts an authenticated loopback server. Automatic groups come from production package/module evidence. In the editor, group labels and group order can be changed, and services can be reordered or moved between groups by drag-and-drop or keyboard controls. Saving persists those choices in the workspace-root .goregraph-dashboard.json; Discard abandons the current draft, and Reset to detected removes saved architecture overrides after confirmation. Rebuilds retain valid manual choices, place newly discovered services into detected groups, and leave removed-service overrides in the config so Doctor can report them as stale.

API Catalog appears before Endpoints. API Catalog is the complete provider inventory, including endpoints with no detected consumer. Endpoints is the relationship and implementation-trace view for consumer-to-provider calls. Endpoint security describes static evidence about what the provider requires; consumer call authentication describes evidence about what one caller sends. Missing evidence is unknown, displayed as No auth evidence detected, never implicitly public. Runtime enforcement and production authorization are outside the scope of static analysis.

For an AI coding task:

goregraph build agent .
goregraph context . --query "<current coding task>" --budget-tokens 4000 --max-files 12

Call goregraph context . --query "<focused query>" exactly once before reading indexed source; put the caller's problem statement and requested evidence scope in the query.
Preserve the caller's domain language, identifiers, and requested evidence; exclude workspace setup, tool policy, safety constraints, and output-format instructions. Do not translate or add inferred repository or component responsibilities.
If the context command fails, do not read context-index.json or any generated index; only a missing or stale output error permits goregraph doctor ., otherwise stop using GoreGraph and follow the caller's fallback policy.
Treat source_sections as current source already read; never re-read, grep, or widen an included range.
If source_coverage is complete, run no source-reading commands on indexed project files. Answer only from source_sections and mark details absent from them as unknown.
If source_coverage is partial or none, inspect only exact project/path and start_line/end_line ranges listed in source_omissions; make the file reader itself range-bounded, for example with sed -n, and never pipe a whole-file reader such as nl through a downstream range filter. Do not inspect outside those ranges or other files. Report pathless or unbounded omissions as uncertainty.
Never inventory repositories or read or grep outside included source_section ranges to reconstruct their files.
A missing future call, route, or symbol required by the requested fix is evidence of the current gap, not a source-fallback trigger; assess entrypoint reliability from the existing production path.
For change plans, include separate exact existing production-file and test-file inventories from files, source_sections, production_plan_files, plan_files, or bounded omission reads; name every supplied production_plan_files identity in the production-file inventory with its role because naming metadata is not reading source; name every supplied plan_files identity in the test-file inventory with its use because naming metadata is not reading source, provider_test entries may be test targets, and mock_pattern or retry_pattern entries are reference patterns, not change targets. Never read production_plan_files or plan_files unless source_omissions lists the same exact path with a bounded range; do not invent future filenames, and keep future route, authentication, status, lookup implementation, dependent persistence and cascade behavior, and cross-service transaction ordering as unknown design decisions unless rendered source proves them.
When authentication or configuration is requested, report supplied server authorization policy, client authentication construction and configuration fields, and exact paths of supplied production and test-profile resources together in one coherent answer section; name every supplied configuration_resources identity with its project, profile, and key groups, and distinguish current evidence, required additions, and unknown deployment values.
If fallback_required is true, confidence is low, or there is not exactly one reliable production entrypoint, stop using GoreGraph.
Retry only when retry_allowed is true: call once with exactly one retry_anchor and --previous-context-id <context_id>; never repeat or expand the original task.
Do not use specialist GoreGraph queries or expert MCP tools.

source_sections are current source already read. With complete source_coverage, run no source-reading commands on indexed project files; answer only from source_sections and mark absent details as unknown. With partial or none coverage, inspect only exact project/path and start_line/end_line ranges in source_omissions; do not inspect outside those ranges or other files, and report pathless or unbounded omissions as uncertainty. source_unrepresented counts visible required concerns without selected source; files remain metadata rather than automatic fallback scope.

For an exact missing-transition change plan, the optional plan_files array adds at most four exact indexed test-source identities without consuming source file, section, or omission slots. provider_test entries name existing provider tests; paired mock_pattern and retry_pattern entries identify caller-side patterns. They are metadata only: do not read them unless source_omissions lists the same path with a bounded range, and do not treat pattern entries as files to change.

The optional production_plan_files array complements that test inventory for the same exact missing-transition requests. Each project group may contain one existing provider_contract path and up to two exact primary-persistence paths. Dependent or comment repositories, test sources, foreign projects, unsafe paths, and identities already represented elsewhere are excluded. These paths are metadata only and never imply that the future route or persistence behavior already exists. To keep the hard token boundary stable, packs with compact plan metadata omit repetitive files.reason text while retaining every file path, range, role, confidence, and source section.

For exact change inventories that request configuration, configuration_resources groups the relevant exact indexed Spring application/bootstrap resource identities by shared project and key_groups; each nested resource contains only path and profile. Selection is capped at six resources before grouping. It makes caller and provider resources explicit without exposing property values or authorizing a read; only a matching bounded source_omissions entry permits inspection.

When a task explicitly asks about types, entities, payloads, identifiers, or lookup attributes, the Context Pack exposes that intent as domain_model. Source selection prefers informative declaration bodies with stable task-domain identity over unrelated one-line cross-cutting signatures. It may retain up to two distinct domain-model and persistence evidence families per project. source_coverage: complete means every required concern has current source; it does not mean that every indexed candidate was serialized. The default limits remain 4,000 tokens, 12 files, and 12 source sections, and complete coverage permits no source-reading commands on indexed project files. Completeness is semantic rather than merely file-based: authentication, configuration, retry/recovery, requested model repositories, and individual side effects must each be present in verified source. Missing facets produce bounded project/path omissions instead of allowing one related section to imply the rest.

Update source safely before scanning

For a single repository, preview the update first and execute it explicitly after reviewing the result:

goregraph git update .
goregraph git update . --execute

The preview is strictly local and uses cached origin references. --execute fetches origin, repeats the safety checks, and only switches or fast-forwards an eligible clean repository. It never stashes, resets, rebases, force-switches, runs repository hooks, or executes project code. Add --format json for structured output.

For a workspace, update each unique Git repository before incrementally updating the projections:

goregraph workspace git update .
goregraph workspace git update . --execute
goregraph workspace update .

Workspace execution continues after blockers so eligible repositories can still update, then returns a non-zero exit code when any repository needs attention. The Git command changes checkouts only; workspace update then detects relevant content changes and rebuilds the affected GoreGraph projects.

Print the generated human report:

goregraph report .

Manual compatibility queries

The specialist query CLI remains available for manual diagnostics and exploration. It is not the normal agent workflow:

goregraph query . StartServer

goregraph query . graph-full
goregraph query . diagnostics
goregraph query . audit

Workspace aliases also work after workspace output exists:

cd ~/projects/acme-workspace
goregraph query . workspace-context
goregraph query . workspace-contracts
goregraph query . workspace-features
goregraph query . workspace-next-actions

Explain one indexed file or symbol:

goregraph explain . src/main.go

Refresh after code changes:

goregraph update [path] [--target agent|dashboard|all]
goregraph workspace update [path] [--target agent|dashboard|all] [--dry-run]

Project update explicitly rebuilds one selected project. workspace update checks every discovered project by relevant file path and content hash, fully rebuilds only changed, new, or incomplete projects, and reconciles the workspace once. Both commands default to --target all; neither installs hooks, runs in the background, or watches files.

Inspect the detected workspace without scanning:

goregraph workspace status .

Preview the highest-value missing service scans without scanning anything:

goregraph workspace scan-missing . --top 5

Run those prioritized scans explicitly:

goregraph workspace scan-missing . --top 5 --execute

Build both projections for every discovered project in the workspace:

goregraph workspace build all .

For the normal incremental workflow after source changes, inspect all projects and rebuild only those whose relevant content changed:

goregraph workspace update . --dry-run
goregraph workspace update .

Change detection compares the actual included file paths and SHA-256 content hashes with each project's existing index/files.json. It therefore detects uncommitted modifications plus added and deleted files without requiring Git. Missing or invalid indexes, an incompatible output schema, and missing selected projections also cause a safe project rebuild. Unchanged project indexes are preserved, and the workspace is reconciled once even when no project needs a rebuild. Use --target agent|dashboard|all, --workspace <path>, and --no-update-gitignore as needed.

goregraph workspace scan-all . remains a compatibility alias for goregraph workspace build all .. Workspace builds scan each discovered project once, then reconcile the workspace once after all project indexes exist. workspace build agent and workspace build dashboard select one projection without rebuilding the other. In contrast, goregraph build <target> . scans only the selected project. It may refresh a detected workspace overlay from existing sibling indexes, but it never scans those sibling projects; add --no-workspace to skip that overlay refresh as well.

Automatic workspace scans require a supported project/build marker at the project root. A .git directory alone identifies a repository for Git operations but is not a scan project. Add a project-local goregraph.yml to opt a non-standard project into automatic discovery. An explicit goregraph build <target> <path> can still scan a deliberately selected markerless directory.

Workspace-wide commands recognize common group layouts such as frontend/, microservices/, services/, and backends/. A flat directory containing sibling projects needs an explicit workspace root:

goregraph workspace build all . --workspace .

Alternatively, add an empty .goregraph-workspace.yml file to the workspace root as a permanent detection marker. A single-project build never requires this marker, and running a build does not create it implicitly. The generated .goregraph-workspace/ directory is removable output, not a permanent marker; goregraph workspace clean . --execute removes that directory but does not remove .goregraph-workspace.yml.

For acceptance of a new GoreGraph binary, rebuild the workspace from clean generated output instead of refreshing older indexes:

goregraph workspace clean .
goregraph workspace clean . --execute
goregraph workspace build all .
goregraph doctor .
goregraph workspace dashboard .

Review the first workspace clean dry run before adding --execute.

Explore exact classes and symbols

Open the generated workspace dashboard, select a service in Architecture, and choose Explore classes & symbols. The Code Explorer keeps the selected service scope and provides:

• a searchable Java / Spring and JavaScript / TypeScript / Node.js / React declaration inventory;
• Direct references for statically resolved source or compile relationships;
• Reached through API for proven HTTP reachability paths;
• separate ambiguity and unresolved evidence instead of choosing a same-name candidate;
• coverage warnings, ordered API path steps, and Copy path / Open source actions for recorded source locations.

Exact selection uses a canonical symbol ID from .goregraph-workspace/index/symbol-index.json. A file name or identifier name alone is not a canonical identity. The following specialist queries are for manual compatibility or explicit goregraph mcp --expert-tools exploration; they are not the normal agent workflow. Resolve human text first, then pass the returned stable ID:

goregraph query . symbol-inventory --query microservices/ms-user --format markdown --limit 20
goregraph query . symbol-resolve --query com.acme.UserService --format json --limit 20
goregraph query . symbol-usages --query symbol:<stable-id> --format markdown --limit 20
goregraph query . symbol-api-consumers --query symbol:<stable-id> --format json --limit 20
goregraph query . symbol-explain --query usage:<stable-id> --detail full --format markdown --limit 20

direct_reference means a static source or compile relationship. It is not a runtime invocation count. reached_through_api means GoreGraph established a static HTTP chain from a consumer through a route and backend implementation to the selected symbol. It is not a direct import and it is not proof that a request occurred at runtime. AMBIGUOUS, UNRESOLVED, incomplete coverage, and an empty result must remain visible when the indexed evidence cannot prove one exact relationship.

Refresh selected workspace projections from existing project indexes without scanning source files:

goregraph workspace refresh . --target agent
goregraph workspace refresh . --target dashboard

Preview and then remove generated GoreGraph workspace output:

goregraph workspace clean .
goregraph workspace clean . --execute

Commands

goregraph help

Show global help.

goregraph build <agent|dashboard|all> [path]

Build one project projection or both. Every build performs source extraction once and writes the shared index/ tree. agent writes the compact AI projection, dashboard writes the human reports, and all writes both.

goregraph scan <path>

Compatibility alias for goregraph build all <path>.

goregraph scan <path> --no-update-gitignore

Scan without adding GoreGraph-generated output paths to .gitignore files.

goregraph scan <path> --no-workspace

Build both project projections and skip workspace discovery/reconciliation.

goregraph scan <path> --workspace <workspace-root>

Build a project while forcing the workspace root used for sibling discovery.

goregraph dashboard .
goregraph dashboard path [path]
goregraph dashboard open [path]
goregraph dashboard edit [path]

Resolve the generated interactive workspace dashboard first when the selected path belongs to a workspace, then fall back to the project's Markdown reports. The bare form and path print the resolved path; open directly opens the workspace workspace-map.html or the fallback dashboard/report.md. If neither exists, GoreGraph reports the build command needed to create one. edit opens the authenticated local editor for the workspace dashboard; it never edits the generated static file directly.

goregraph workspace dashboard [path]
goregraph workspace dashboard path [path]
goregraph workspace dashboard open [path]
goregraph workspace dashboard edit [path]

The bare compatibility form and path print the generated static workspace dashboard; open opens that static read-only file. Only edit starts an authenticated loopback editor and saves layout choices to the workspace-root .goregraph-dashboard.json.

goregraph context <path> --query <task> [--budget-tokens 4000] [--max-files 12]

Compile one bounded Context Pack from agent/context-index.json. This is the normal AI workflow; the source-backed read rules are stated in the Quick Start.

goregraph update

Refresh both project projections. Use --target agent|dashboard|all to refresh only the selected projection; omitted target defaults to all.

goregraph git update [path]

Preview a strictly local safe Git update. Add --execute to fetch and apply an eligible switch or fast-forward, and add --format json for structured output.

goregraph workspace git update [path]

Preview safe updates for every unique Git repository in a detected workspace. Add --execute to fetch and apply eligible updates.

goregraph report <path>

Print <path>/goregraph-out/dashboard/report.md.

goregraph query <path> <term>

Search the generated index for matching files, symbols, and relations.

goregraph explain <path> <file-or-symbol>

Print indexed context for a file path or symbol name.

goregraph doctor <path>

Check generated output health without scanning.

goregraph workspace status <path>

Show discovered workspace projects, indexed projects, known backend services, and referenced but missing services without scanning or writing files. Missing services are prioritized by the number of referenced contracts and include scan suggestions when GoreGraph found a matching workspace project.

goregraph workspace scan-missing <path>

Show a prioritized missing-service scan plan without scanning. By default this is a dry run and shows the top 5 unindexed services with the most referenced frontend contracts.

goregraph workspace scan-missing <path> --top 5 --execute

Scan the selected top-N missing service projects and refresh workspace overlays. Use --no-update-gitignore to skip generated-output .gitignore updates.

goregraph workspace build <agent|dashboard|all> [path]

Scan every discovered project once and reconcile the workspace once for the selected projection or both. Use --dry-run to print the plan.

goregraph workspace update [path] [--target agent|dashboard|all] [--dry-run]

Content-check every discovered project, rebuild only changed or incomplete projects, and reconcile the workspace once. The default target is all. --dry-run prints each project's build or skip decision and added, modified, and deleted file counts without writing output.

goregraph workspace scan-all <path>

Compatibility alias for goregraph workspace build all <path>. For a flat directory of sibling projects, pass --workspace <path> or add .goregraph-workspace.yml to the workspace root so detection still works after generated workspace output is cleaned.

goregraph workspace refresh [path] [--target agent|dashboard|all]

Refresh workspace projections from existing project indexes without scanning source files. Use --target agent|dashboard|all; omitted target defaults to all.

goregraph workspace dashboard [path]
goregraph workspace dashboard path [path]
goregraph workspace dashboard open [path]
goregraph workspace dashboard edit [path]

The bare compatibility form and path print the static read-only .goregraph-workspace/dashboard/workspace-map.html; open opens that file. Only edit starts an authenticated loopback editor and persists saved layout choices in the workspace-root .goregraph-dashboard.json.

goregraph workspace clean <path>

Show generated GoreGraph output paths for the detected workspace without deleting anything. Add --execute to remove project goregraph-out/ directories and the workspace .goregraph-workspace/ directory.

goregraph workspace diff --before <workspace-output> --after <workspace-output>

Compare two generated .goregraph-workspace output directories without scanning source files.

goregraph workspace explain <target>

Explain generated workspace evidence for a route, file, symbol, contract, or feature.

goregraph workspace path --from <target> --to <target>

Find a directed path between two generated workspace targets.

goregraph workspace impact --changed-file <path>

Show features and relationships that may be affected by one or more changed files.

goregraph mcp

Start the read-only MCP stdio server with exactly task_context. Use goregraph mcp --expert-tools only for explicit manual diagnostics and legacy exploration.

goregraph version

Print build metadata including version, commit, build date, Go version, platform, and schema version.

Language Coverage

Coverage describes implemented static analyzers, not proof that runtime behavior is absent. Full adapters emit normalized symbols, relations, calls, routes, and tests for their supported syntax. Pattern-backed capabilities recognize only the listed static families. Integration and Index are intentionally shallower. — means unavailable.

Language / framework	Adapter	Symbols	Imports	Calls	Routes	Tests	API clients	Persistence	Messaging / RPC	Data flow	Exact symbols	Direct usages	HTTP reachability
C	Index	Index	Index	—	—	—	—	—	—	—	—	—	—
C++	Index	Index	Index	—	—	—	—	—	—	—	—	—	—
C#	Index	Index	Index	—	—	—	—	—	—	—	—	—	—
Go	Full	Full	Full	Full	Full	Full	Pattern-backed	Pattern-backed	Pattern-backed	Pattern-backed	—	—	—
Java / Spring	Full	Full	Full	Full	Full	Full	Pattern-backed	Pattern-backed	Pattern-backed	Pattern-backed	Full	Full	Provider
JavaScript / TypeScript / Node.js / React	Full	Full	Full	Full	Full	Full	Pattern-backed	Pattern-backed	Pattern-backed	Pattern-backed	Full	Full	Consumer + provider
Kotlin	Index	Index	Index	—	—	—	—	—	—	—	—	—	—
PHP	Full	Full	Full	Full	Full	Full	Pattern-backed	Pattern-backed	Pattern-backed	Pattern-backed	—	—	—
Python	Full	Full	Full	Full	Full	Full	Pattern-backed	Pattern-backed	Pattern-backed	Pattern-backed	—	—	—
Ruby	Index	Index	Index	—	—	—	—	—	—	—	—	—	—
Rust	Full	Full	Full	Full	Full	Full	Pattern-backed	Pattern-backed	Pattern-backed	Pattern-backed	—	—	—
Scala	Index	Index	Index	—	—	—	—	—	—	—	—	—	—
Shell	Integration	Integration	Integration	Integration	—	—	—	—	—	—	—	—	—
Swift	Index	Index	Index	—	—	—	—	—	—	—	—	—	—

Pattern-backed extraction can miss runtime-generated behavior such as routes, reflective or dynamic dispatch, metaprogramming, dependency-injection aliases, arbitrary client wrappers, ORM behavior assembled at runtime, and configuration outside indexed source. Missing static evidence is not proof of runtime absence.

Shell integration does not provide routes, tests, or architecture capabilities. Index adapters provide best-effort declarations and imports only; they do not provide normalized calls, routes, tests, or architecture facts.

Supported static pattern families:

• Go: net/http and common routers; net/http clients; database/sql and GORM; Kafka and AMQP; gRPC; JSON request/response boundaries; go test and httptest.
• Java / Spring: Spring MVC and WebFlux; Java and Spring HTTP clients; Spring Data; Spring Messaging; gRPC; Jakarta Validation; JUnit and Spring Test.
• JavaScript / TypeScript / Node.js / React: Express and Fastify; NestJS; Next.js; Web and Node HTTP clients; common Node persistence; Kafka and AMQP; gRPC; Node request/response boundaries; Jest, Vitest, Node Test, and React Testing Library.
• PHP: Laravel and Symfony routes; PHP HTTP clients; Eloquent, Doctrine, and PDO; queues and messaging; gRPC; PHP request/response boundaries; PHPUnit and Pest.
• Python: FastAPI, Flask, and Django routes; requests, httpx, and aiohttp; SQLAlchemy, Django ORM, and DB-API; Kafka, Celery, and AMQP; gRPC; Python web and validation boundaries; pytest and unittest.
• Rust: Axum, Actix, and Rocket routes; reqwest; SQLx, Diesel, and SeaORM; Kafka and AMQP; tonic gRPC; Rust web request/response boundaries; Rust and Tokio tests.

For HTTP reachability, Provider means a supported Java/Spring or Node.js provider chain. Consumer + provider means supported JavaScript/TypeScript frontend origins plus supported Node.js handlers. These are static, evidence-backed relationships, not runtime reachability guarantees.

API integration depth

This table describes the API Catalog, dashboard, and compact agent projection; it does not turn missing static evidence into a runtime claim.

Language / framework	Endpoint inventory	Consumers	Security/auth	Request/response types	Dashboard	Agent context
Java / Spring	Provider endpoints	Reconciled callers	Endpoint security	Statically extracted DTO identities	Full API Catalog and Endpoints	Relevant endpoint facts
JavaScript / TypeScript / Node.js / React	Supported Node provider routes	HTTP client call sites	Consumer call authentication; provider security unknown	Handler identity; request/response types unknown	Full API Catalog and Endpoints	Relevant endpoint and consumer facts
Go, PHP, Python, Rust	Pattern-backed route facts	Pattern-backed client facts; no reconciled consumer/provider chain	Not projected into canonical endpoint security	Pattern-backed request/response boundaries	Architecture evidence; no canonical API reachability	Relevant route, client, persistence, messaging, data-flow, and test facts

For all rows, unknown means evidence was not detected. It does not mean an endpoint is public or that authentication is absent at runtime.

Output Files

Project output has three owned subtrees:

goregraph-out/
  manifest.json
  index/                  # canonical machine index used by GoreGraph
    api-catalog.json      # complete project provider inventory
  agent/
    context-index.json    # only generated index recommended for AI context
    agent-guide.md
  dashboard/              # human-readable project reports
    report.md
    ...

Workspace output uses the same ownership split:

.goregraph-workspace/
  manifest.json
  index/                  # registry, canonical graphs, symbols, usages, flows
    api-catalog.json      # complete workspace provider inventory
  agent/
    context-index.json
    agent-guide.md
  dashboard/
    workspace-map.html    # interactive human workspace dashboard
    workspace-map-assets/
    ...                   # human-readable workspace reports

index/ is GoreGraph's complete shared machine index and is not intended for direct prompt ingestion. agent/ and bounded Context Packs are the only recommended AI input. dashboard/ is the full human exploration surface; Code Explorer remains there. Project dashboard builds produce Markdown reports, while the interactive dashboard remains workspace-only in 1.3.0.

The user-owned .goregraph-dashboard.json sits at the workspace root, outside generated output. It stores stable group order, labels, and service placement; dashboard rebuilds read it but do not overwrite it. The complete index/api-catalog.json is machine/dashboard input, not prompt input.

The JSON files described below live under index/; human-readable Markdown files live under dashboard/ unless stated otherwise.

manifest.json contains scan metadata:

• tool name
• schema version
• output directory
• scanned file count
• skipped file count
• generated files
• project root name

files.json contains indexed files with root-relative paths:

• path
• language
• size
• SHA-256 hash
• kind

symbols.json contains simple extracted symbols:

• name
• kind
• root-relative file path
• line number

relations.json contains simple extracted relations:

• source file
• target
• relation type
• line number

graph.json contains combined nodes and edges derived from files, symbols, and relations.

callgraph.json contains method/function call edges with confidence metadata.

routes.json contains normalized backend and frontend route records.

flows.json contains route-to-handler-to-call flow records.

api-contracts.json contains statically detected Java/Spring and JavaScript/TypeScript HTTP client contracts. Java supports imported Spring declarative clients plus bound RestClient, WebClient, and RestTemplate receivers; JavaScript/TypeScript supports recognized helpers, request wrappers, and fetch. Records preserve method, raw and normalized path, query metadata, service candidate, caller, source location, confidence, and unresolved dynamic path evidence. Java records may also expose sorted, value-free configuration_key_groups derived from real Spring @Value or @ConfigurationProperties imports. api-contracts.md renders the same static contract evidence for humans.

service-dependencies.json contains backend service-client relationships extracted from Java source, for example imports or fields referencing shared clients such as UserMgmtService, ProductServiceMgmt, or LicenseMgmtService. Workspace service maps merge these backend-to-backend dependencies with frontend API contract relationships.

frontend-usage.json and frontend-usage.md connect detected frontend API contracts back to the best matching frontend route flow. They show route ID/path, component, API caller, confidence, and the static evidence chain when a route flow reaches the API contract file or caller.

contract-matches.json compares detected frontend API calls with backend routes discovered in the same scan. Exact method and compatible path patterns are marked RESOLVED; method mismatches, missing backend routes, unscanned services, and unsafe dynamic URL patterns are reported as weak/static findings. contract-matches.md is the readable match view, while potentially-broken-contracts.md focuses on issues that deserve manual review.

diagnostics.json and diagnostics.md summarize the most useful diagnostic entrypoints: top routes/endpoints, risky contracts, workspace-resolved contracts, unscanned services, endpoints without detected tests, weak inferred flows, and likely tests.

Workspace canonical records such as registry.json, context.json, contract-matches.json, feature-flows.json, workspace-graph.json, symbol-index.json, and symbol-usages.json live under .goregraph-workspace/index/. Human summaries and project-relevant overlay reports live under the corresponding dashboard/ tree. Workspace reconciliation updates these projections once after all selected project indexes are available.

The workspace dashboard at .goregraph-workspace/dashboard/workspace-map.html is a standalone offline UI with eight top-level views, including a directly accessible Code Explorer. Its generated .goregraph-workspace/dashboard/workspace-map-assets/ directory keeps project-specific symbol-usage evidence out of the startup document and loads it only when Code Explorer is opened; keep that directory next to the HTML file when moving the offline dashboard:

• Architecture: understand how projects and services communicate without losing the full workspace layout. Dynamic domain lanes come from service-map metadata. Selecting a service keeps every card at its stable position, highlights all direct incoming and outgoing relationships, and dims unrelated context. Background relationships share bundled trunks; selected relationships fan out to explicit card ports. The persistent summary shows relationship, neighboring-service, resolved, unresolved, and mismatch counts and filters by direction or risk. N calls means statically detected relationships, not runtime request frequency.
• API Catalog: inspect the complete provider inventory, including endpoints without known consumers, static parameters, media types, request and response identities, provider security, and per-consumer evidence.
• Endpoints: search for and select a service, inspect its caller -> endpoint -> provider rows in a normal-scale scrollable workbench, then open an endpoint to follow its implementation trace. Long routes wrap instead of shrinking the whole inventory. Long implementation traces start with readable cards at 100%; pan explores the path and Fit explicitly shows the complete overview.
• Feature Flow: inspect the evidence-backed route-to-component-to-API-to-backend-to-persistence-to-test implementation chain, linked tests, and safe verification commands.
• Data Flow: select one endpoint from the sidebar, then inspect its evidence-backed request fields, transformations, persistence, and response fields as a readable chain. Unknown mappings are displayed at their position as explicit gaps instead of invented connections.
• Code Explorer: select a service with indexed classes and symbols, search its inventory, and inspect Direct references, Reached through API paths, uncertainty, and source evidence without compressing the inventory into an SVG. The same workbench remains available from a selected Architecture service.
• Diagnostics: review relationships GoreGraph could not safely confirm, why each result matters, its available evidence, and what to check next. Categories distinguish likely code defects, missing scan coverage, dynamic or statically ambiguous paths, and expected frontend-internal behavior.
• Coverage: inspect which language and framework capabilities were analyzed completely, partially, not at all, or with a failure. A normal-scale workbench groups the capability inventory by project and language and summarizes analyzed groups, analyzer gaps, partial capabilities, and failures. Coverage describes analyzer support and is not proof that a source-code behavior is absent.

Endpoints provides multi-select HTTP method filters, separate caller and provider service filters, and resolution-status filters. Filters remain active while a trace is open and after returning to the endpoint inventory.

evidence.json stores deterministic root-relative source evidence with stable IDs. Generated route and call facts reference those records through additive evidence_ids. capabilities.json, coverage.json, and coverage.md report analyzer support separately from relationship confidence, match resolution, and diagnostic severity.

The analysis remains static and pattern-backed. Runtime-generated routes, reflective dispatch, arbitrary client wrappers, dependency-injection aliases, ORM metaprogramming, and configuration assembled outside indexed source may remain gaps. A relationship absent from GoreGraph is therefore not proof that it does not exist at runtime; inspect the cited evidence and diagnostics before drawing operational conclusions.

package-graph.json contains Node workspace package nodes and package-to-package dependency edges from package.json.

maven-graph.json contains Maven package nodes and dependency edges extracted from pom.xml.

navigation.md summarizes likely starting points, central local files, important symbols, test orientation, and analyzer coverage.

affected.md lists local files with inbound impact signals. It filters external packages such as react or design-system imports so the report is better suited for concrete change-impact orientation.

report.md is a human-readable deterministic project report.

modules.md summarizes top-level project areas.

entrypoints.md lists likely app, CLI, and package-script entrypoints.

test-map.md lists best-effort source/test associations.

All normal output paths are relative to the scanned project root.

MCP Mode

goregraph mcp starts a read-only stdio server. Standard mode exposes exactly one tool: task_context. It returns the same bounded Context Pack as the direct context command and follows the same source-backed workflow.

It:

• reads only the existing agent/context-index.json needed for Context Packs;
• exposes task_context in standard mode;
• does not scan automatically, write project files, or open a network port.

Run goregraph build agent . first, then point the MCP client at goregraph mcp. Use goregraph mcp --expert-tools only for explicit manual diagnostics or legacy exploration. Expert tools are not a fallback cascade after the one-call/at-most-one-retry Context workflow.

Prepare a project

GoreGraph must be installed on PATH. Verify the installation from a new terminal:

goregraph version

Before using GoreGraph in Codex, generate the local index from the project root:

cd C:\path\to\project
goregraph scan .

scan builds both the agent and dashboard projections. To generate only the data required by the MCP server, run:

goregraph build agent .

The MCP server is read-only and does not run a scan automatically. Refresh the agent index after relevant source changes:

goregraph update . --target agent

Connect GoreGraph to Codex

The ChatGPT/Codex desktop app, Codex CLI, and Codex IDE extension share the same local MCP configuration. ChatGPT web cannot start this local stdio server.

The recommended setup uses the Codex CLI:

codex mcp add goregraph -- goregraph mcp
codex mcp list

Restart Codex after adding the server. In the desktop app or Codex terminal, enter /mcp and verify that goregraph is connected and exposes task_context.

Alternatively, open ~/.codex/config.toml and add:

[mcp_servers.goregraph]
enabled = true
command = "goregraph"
args = ["mcp"]

In the desktop app, the same configuration can be added through Settings → MCP servers → Add server:

1. Enter goregraph as the server name.
2. Select STDIO.
3. Enter goregraph as the command.
4. Add mcp as the argument.
5. Save the server and restart Codex.

Codex starts and stops goregraph mcp automatically. Do not start a separate MCP process manually after configuring the server.

Use GoreGraph in Codex

Open the indexed project as the active Codex workspace and ask Codex to use the GoreGraph task_context tool for the coding task. For example:

Use GoreGraph task_context to identify the current implementation path,
affected files, and relevant tests before reading additional source files.

If the server is not available, verify the installation and configuration:

Get-Command goregraph
goregraph version
codex mcp list

After installing GoreGraph or changing PATH, close and restart all terminals and Codex clients before testing the MCP connection.

Exclusions

GoreGraph skips common generated, dependency, build, VCS, editor, and local output paths by default:

.git/
node_modules/
vendor/
target/
build/
dist/
coverage/
.idea/
.vscode/
.gitignore
goregraph-out/
.goregraph-workspace/

It also skips:

• binary files
• files over the configured size limit
• symlinks by default

Generated Output .gitignore

GoreGraph reads the project .gitignore and uses it as additional scan exclusions.

By default, goregraph scan also ensures the project .gitignore contains:

# GoreGraph local scan output
goregraph-out/

This prevents local scan output from being committed.

When workspace discovery is active and a workspace root is detected, GoreGraph also ensures the workspace root .gitignore contains:

# GoreGraph local workspace output
.goregraph-workspace/

This prevents central workspace overlays from being committed when the workspace root itself is a Git repository.

To opt out:

goregraph scan . --no-update-gitignore

GoreGraph only modifies .gitignore files in the scanned project and detected workspace root. It does not modify global Git config.

Configuration

GoreGraph works without config. Projects can optionally add:

goregraph.yml

Supported keys:

version: 1
output: goregraph-out
include:
  - src/**
  - tests/**
exclude:
  - generated/**
max_file_size_kb: 512
follow_symlinks: false
use_gitignore: true
update_gitignore: true

Config values are merged with built-in safety defaults. Configured exclude patterns are added to the default exclusions; they do not remove safety exclusions such as .git/ or node_modules/.

include limits the scan to matching root-relative paths. If include is omitted, GoreGraph scans the whole project except exclusions and safety skips.

The configured output directory is used by scan, report, query, and explain.

Unsupported nested config sections are intentionally rejected for now so configuration mistakes do not silently change scan behavior.

Explain Context

goregraph explain . src/main.go

explain prints:

• file metadata
• symbols in the file
• outbound relations
• inbound relations
• likely tests

Compact task context

Use the direct command for normal agent work:

goregraph context <path> --query "<current coding task>" --budget-tokens 4000 --max-files 12

The result contains bounded entrypoints, relationships, tests, risks, source files, evidence IDs, confidence, freshness, and explicit uncertainty. The public query is the normalized request text verbatim when it is at most 256 runes and its JSON encoding is at most 256 bytes; otherwise it is a compact primary-task summary. The complete request remains internal to that request lifecycle for selection and is neither emitted nor included in the Context ID hash.

Call goregraph context . --query "<focused query>" exactly once before reading indexed source; put the caller's problem statement and requested evidence scope in the query.
Preserve the caller's domain language, identifiers, and requested evidence; exclude workspace setup, tool policy, safety constraints, and output-format instructions. Do not translate or add inferred repository or component responsibilities.
If the context command fails, do not read context-index.json or any generated index; only a missing or stale output error permits goregraph doctor ., otherwise stop using GoreGraph and follow the caller's fallback policy.
Treat source_sections as current source already read; never re-read, grep, or widen an included range.
If source_coverage is complete, run no source-reading commands on indexed project files. Answer only from source_sections and mark details absent from them as unknown.
If source_coverage is partial or none, inspect only exact project/path and start_line/end_line ranges listed in source_omissions; make the file reader itself range-bounded, for example with sed -n, and never pipe a whole-file reader such as nl through a downstream range filter. Do not inspect outside those ranges or other files. Report pathless or unbounded omissions as uncertainty.
Never inventory repositories or read or grep outside included source_section ranges to reconstruct their files.
A missing future call, route, or symbol required by the requested fix is evidence of the current gap, not a source-fallback trigger; assess entrypoint reliability from the existing production path.
For change plans, include separate exact existing production-file and test-file inventories from files, source_sections, production_plan_files, plan_files, or bounded omission reads; name every supplied production_plan_files identity in the production-file inventory with its role because naming metadata is not reading source; name every supplied plan_files identity in the test-file inventory with its use because naming metadata is not reading source, provider_test entries may be test targets, and mock_pattern or retry_pattern entries are reference patterns, not change targets. Never read production_plan_files or plan_files unless source_omissions lists the same exact path with a bounded range; do not invent future filenames, and keep future route, authentication, status, lookup implementation, dependent persistence and cascade behavior, and cross-service transaction ordering as unknown design decisions unless rendered source proves them.
When authentication or configuration is requested, report supplied server authorization policy, client authentication construction and configuration fields, and exact paths of supplied production and test-profile resources together in one coherent answer section; name every supplied configuration_resources identity with its project, profile, and key groups, and distinguish current evidence, required additions, and unknown deployment values.
If fallback_required is true, confidence is low, or there is not exactly one reliable production entrypoint, stop using GoreGraph.
Retry only when retry_allowed is true: call once with exactly one retry_anchor and --previous-context-id <context_id>; never repeat or expand the original task.
Do not use specialist GoreGraph queries or expert MCP tools.

For an endpoint task, the compact projection keeps at most one selected endpoint and eight consumer call sites with an explicit omitted count. It preserves the 4000-token default budget and does not include the full index/api-catalog.json, dashboard payload, or .goregraph-dashboard.json.

Legacy query task-context, workspace-delta, diagnostics, service-context, and other specialist queries remain available for manual compatibility. They are not part of the normal AI workflow. Workspace-root Context Packs remain neutral and derive requested scope only from the actual invocation.

Agent workflow skills and plugins

Normal GoreGraph use remains compatible with Brainstorming, TDD, debugging, and review skills. The generated Agent Guide should remain the authority for source acquisition; complementary workflow skills should run after the guide and Context Pack have established the source boundary.

Always-on bootstrap or broad debugging skills that require their own reads before project instructions can preempt that workflow. Their precedence is controlled by the agent host, not by GoreGraph. For controlled benchmarks, external_skill_read_calls is plugin-agnostic transcript evidence: it counts read or search targets outside the benchmark workspace that resolve to a skill bundle. Both controlled variants require zero external skill reads across the complete transcript. --ignore-user-config is not a skill-isolation guarantee. The harness records plugin state but never mutates it. Do not add skill-control instructions to the task prompt.

Agent context benchmark and release gate

The 1.3.0 Context integration uses a matched-prompt three-by-three benchmark: three independent baseline and assisted Codex runs alternate against the same immutable workspace, neutral base prompt, model, reasoning setting, sandbox, approval mode, and other execution arguments. Every raw transcript is retained outside the repository.

Both raw and effective counters are retained. effective_tokens is input_tokens - cached_input_tokens + output_tokens, or uncached input plus output; total_tokens is input_tokens + output_tokens. Reasoning output is recorded separately but is already part of output, so reasoning output is not double-counted. The 80% matched threshold uses effective tokens, and the 116,560 absolute cap uses effective tokens. Release also requires tool calls at most 70% of baseline, source reads at most 50% of a nonzero baseline, and no repeated full assisted Context Pack. A manually completed, externally retained and signed 12-point evidence rubric must score assisted quality at least as high as baseline quality. Context Pack estimated_tokens remains unrelated to end-to-end usage.

The last controlled three-by-three release benchmark passed for candidate 0edc6d8. Effective-token medians were 142796 baseline and 20105 assisted, an 85.92% reduction; mean effective tokens were 138549 baseline and 23000 assisted, an 83.40% reduction. Tool-call medians were 28 and 3, and source-read medians were 19 and 2. All six runs had zero external skill reads. The signed 12-point review scored baseline quality at a median of 11 and assisted quality at 12, with every assisted run scoring 12/12. That result qualifies the runtime candidate 0edc6d8 and the final release descendant, whose later changes are confined to documentation, tests, and documentation-sync tooling. This evidence covers one frozen historical three-repository Java case and is not a general token-savings guarantee.

The previous failed controlled result remains retained and is not rescored. The passing matrix above qualifies runtime candidate 0edc6d8 and the final release descendant, whose later changes are confined to documentation, tests, and documentation-sync tooling. A different runtime candidate requires a fresh matched matrix before publication, which remains a separate explicit release action.

Independently of that external efficiency gate, repository tests now exercise source-derived transfer on a synthetic three-service Java workspace with unrelated order, client-library, and inventory names. The test requires one public entrypoint, a unique resolved secondary contract/provider path, exact value-free Spring configuration evidence, persistence, side effects, tests, retained uncertainty for the intentionally missing call, deterministic output, and no private benchmark vocabulary. The committed G2–G6 matrix remains a separate regression gate. These checks guard transfer beyond the historical benchmark case; they are not token-savings measurements.

The benchmark consumes Codex JSONL logs and distinguishes compact duplicate_of Context Packs from a repeated full payload: compact duplicates are retained as diagnostic evidence, while a repeated full context_id fails the release gate.

The exact one-line baseline instruction, thirteen-line assisted instruction, execution protocol, rubric, and dashboard-only decision when a gate fails are defined in docs/BENCHMARKING.md. A failed gate blocks the 1.3.0 release.

Security Model

GoreGraph is local and explicit.

GoreGraph does not:

• call AI providers
• access the network during scans, Git-update previews, or other read-only commands
• install Git hooks
• modify agent instruction files
• modify editor settings
• run background daemons
• follow symlinks by default

GoreGraph does:

• read files under the selected scan root
• write to goregraph-out/
• write workspace registry/overlay files under a detected workspace root and already indexed sibling output directories
• fetch origin and safely switch or fast-forward eligible repositories only when a Git update command with --execute is explicitly requested
• optionally update project and workspace root .gitignore files for generated GoreGraph output

API security and authentication results are static source evidence. Endpoint security and consumer call authentication remain separate, unknown is shown as No auth evidence detected rather than public, and GoreGraph does not claim to validate runtime enforcement or production authorization.

License

Apache-2.0. See LICENSE.