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

Measured token use

The latest completed normal-MCP development comparison saved 32.97% effective tokens across two unchanged pairs on one frozen diagnosis task. The assisted answers scored 11/12 and 10/12 static criteria, compared with 9/12 for both controls; they still missed one conditional side effect. See the measurement and its limits.

The older 52.08% figure is a separate macOS 1.4.1 development experiment (79,464 versus a previously saved 165,839-token reference). Its baseline was not rerun alongside that candidate. See the historical follow-up. Neither figure is a general savings guarantee. The current answer-check and instruction changes were made after the latest measured series; no new percentage is claimed.

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 opens with Architecture, Interfaces, Service Code and Data Quality. The same selected service carries across these views. Extended analysis tools retain Feature Flow, Data Flow and layout editing. All displays use the existing evidence-backed local projections.

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.

1.4.3 — Unreleased

The development source version is 1.4.3. No release or tag has been created for this version; v1.4.2 remains the published release.

The regular MCP server now defaults to adaptive-v2, matching the existing adaptive CLI workflow. Incomplete context can lead to bounded verification or caller-authorized source fallback. Explicit strict-v1 replay and tooling-audit boundaries remain available. Optional parameter limits are described in plain language, and invalid budget/file limits are reported together. Persistent agent instructions must allow the selected protocol while keeping GoreGraph ahead of optional skills.

Explicit tooling inventories now use task_context with mode: "audit" or goregraph context --mode audit. Both context protocols return bounded current sources for Storybook configuration, stories and their literal file references, package scripts, runner configuration, local CI includes, visual-test preparation and documentation. Audits allow multiple source roots, retain the full query for retrieval and report scoped coverage, static links and unknowns. Audit support does not alter ordinary production-entrypoint selection.

The mandatory synthetic acceptance test delivers all seven Storybook evidence groups. A second multi-project test covers Playwright deployment triggers, INT/TEST, frontend release versus Playwright master, explicit service-to-app mappings and non-blocking failure policy. Source configuration never establishes successful execution or approved visual baselines. See tooling audits for limits, examples and index refresh requirements.

The offline dashboard adds Tests & Tooling under Service Code: a project-scoped, searchable inventory with source links and literal A11y/CI declarations. An optional, explicit JUnit import adds separate result evidence from local files. No import remains neutral. GoreGraph does not run tests, contact CI or store CI credentials; imported reports do not certify a pipeline or the current checkout. See tooling audits and result import.

An optional local watcher now refreshes the agent index and dashboard after source changes. It starts only on request; login autostart is a separate per-user choice on Windows, macOS, and Linux.

1.4.2 — Workspace Explorer

Version 1.4.2 makes the redesigned Workspace Explorer the default offline dashboard.

The offline Workspace Explorer now opens with four areas: Architecture, Interfaces, Service Code and Data Quality. Service selection is shared across areas. Architecture shows a directed domain matrix and service focus with side-by-side evidence. Interfaces combine offered APIs and consumer traces. Service Code shows canonical symbols with grouped incoming and outgoing usages, source lines and separate API-reachability evidence. Data Quality combines coverage and diagnostic drilldowns. Existing Feature Flow, Data Flow and layout editing remain available under the extended analysis tools.

Only dashboard presentation changes: source indexing, reconciliation, agent/MCP contracts, Schema 3 and original grouping assignments remain unchanged. Usage evidence continues to load from the existing offline assets; retain workspace-map-assets next to workspace-map.html.

Installation

Source version: GoreGraph 1.4.3 with output Schema 3.

v1.4.2 is the current GoreGraph release. Package-manager indexes can take some time to ingest a new release, so always verify the installed version with goregraph version after installing or upgrading.

Version 1.4.1 added scoped Git ignore rules, faster script analysis, cancellable builds with file/phase progress, input-aware updates, recoverable output publication, explicit partial/stale health, adaptive evidence retrieval, bounded source reads with pagination, and answer citation validation. Version 1.4.3 defaults MCP to adaptive-v2; pass --protocol strict-v1 when strict replay is required.

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 Scoop and automatically opens the upstream Winget manifest PR when their repository tokens are configured.

Winget Windows — recommended

Winget is the recommended installation method on Windows. GoreGraph is available from the public Winget source under the stable package ID GoreCode.GoreGraph:

winget install --id GoreCode.GoreGraph --exact --source winget
goregraph version

Upgrade an existing installation with:

winget upgrade --id GoreCode.GoreGraph --exact --source winget

The 1.4.2 release workflow publishes the release archives and automatically submits the corresponding Winget manifest update. Microsoft must accept and publish that manifest before Winget offers 1.4.2. If winget is missing, install or update App Installer from Microsoft Store and open a new terminal.

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 — alternative

Scoop is an alternative when Winget cannot be used. For the normal per-user installation, open a regular, non-administrative PowerShell and run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

If Scoop reports that the current PowerShell is running as Administrator, reopen PowerShell without Run as administrator and use the command above. When an administrator installation is explicitly required and permitted, use Scoop's official advanced installer from an elevated PowerShell:

irm get.scoop.sh -OutFile install.ps1
.\install.ps1 -RunAsAdmin
Remove-Item .\install.ps1

If company policy prevents changing the execution policy or you do not have the required rights, use Winget or the manual installation below. Do not try to override an organization-managed policy. Proxy, custom-directory, and additional bootstrap options are documented in 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 installation

Manual installation requires more than extracting the archive: the directory containing the GoreGraph executable must be on PATH. Otherwise goregraph works only when invoked with its full or relative path, and Codex cannot reliably start goregraph mcp.

Windows

Download the current Windows x86-64 archive directly:

Download goregraph_Windows_x86_64.zip

This link currently downloads the published 1.4.2 archive. A ready-to-use 1.4.3 Windows executable can be linked here after its binary asset is published.

This ZIP is a portable archive, not an installer. Extracting it does not add GoreGraph to PATH; complete the following steps before using goregraph from PowerShell, Command Prompt, an IDE, or Codex.

Extract the ZIP into a stable directory, for example %LOCALAPPDATA%\Programs\GoreGraph\bin, and place goregraph.exe directly in that directory. Then add the directory to your user PATH:

Open Start and search for Edit environment variables for your account.
Under User variables, select Path, choose Edit, then New.
Add the directory that contains goregraph.exe and confirm all dialogs.
Close and reopen PowerShell, Command Prompt, your IDE, and Codex.

Verify from the new terminal:

Get-Command goregraph
goregraph version

Running .\goregraph.exe version inside the extraction directory alone does not prove that the PATH configuration works.

macOS and Linux

Download and extract the matching archive, then install the executable in a stable directory. A per-user location that does not require administrator rights is ~/.local/bin:

mkdir -p "$HOME/.local/bin"
install -m 0755 goregraph "$HOME/.local/bin/goregraph"

Ensure that directory is on PATH. On macOS with the default Z shell, add the following line to ~/.zshrc; on Linux, add it to ~/.profile or your shell's equivalent startup file:

export PATH="$HOME/.local/bin:$PATH"

Open a new terminal, then verify:

command -v goregraph
goregraph version

For a system-wide installation, /usr/local/bin is commonly already on PATH:

sudo install -m 0755 goregraph /usr/local/bin/goregraph

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 an archive, follow the manual installation steps above so the executable is available from every project directory.

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 "" --budget-tokens 4000 --max-files 12

Call goregraph context . --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 ; 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 , 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 . 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 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: --format markdown --limit 20
goregraph query . symbol-api-consumers --query symbol: --format json --limit 20
goregraph query . symbol-explain --query usage: --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  [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

Compatibility alias for goregraph build all .

goregraph scan  --no-update-gitignore

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

goregraph scan  --no-workspace

Build both project projections and skip workspace discovery/reconciliation.

goregraph scan  --workspace

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  --query  [--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

Print /goregraph-out/dashboard/report.md.

goregraph query

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

goregraph explain

Print indexed context for a file path or symbol name.

goregraph doctor

Check generated output health without scanning.

goregraph workspace status

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

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

Compatibility alias for goregraph workspace build all . For a flat directory of sibling projects, pass --workspace 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

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

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

goregraph workspace explain

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

goregraph workspace path --from  --to

Find a directed path between two generated workspace targets.

goregraph workspace impact --changed-file

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 Workspace Explorer with four main areas: Architecture, Interfaces, Service Code, and Data Quality. Service selection is shared between them. 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 integration

What MCP is and what GoreGraph exposes

The Model Context Protocol (MCP) is an open standard that lets an AI client call external tools through a defined interface. For GoreGraph, the client starts goregraph mcp as a local child process and communicates with it over standard input/output (stdio). It is not a daemon: there is no background service to start manually, no network listener, and no remote GoreGraph service.

Standard mode exposes exactly one read-only tool, task_context. The default MCP protocol is adaptive-v2: it supplies bounded verification requests and explicit fallback signals when the initial pack cannot cover the task. Use goregraph mcp --protocol strict-v1 for the historical bounded-only contract. The standalone goregraph context CLI keeps its historical strict default; use --protocol adaptive-v2 to match the regular MCP workflow. No index rebuild is needed solely for this protocol change. Restart the MCP client after updating GoreGraph so it loads the new server instructions. For a focused coding question, that tool uses the same bounded, evidence-backed Context Pack compiler as goregraph context. The pack contains the selected implementation path, line-numbered source sections, affected files, relevant tests, confidence, freshness, and explicit gaps. The MCP server:

reads the existing agent index;
does not scan or execute project code;
does not modify project files;
does not open a network port;
is started and stopped automatically by the configured AI client.

Registering the server makes the tool available. It does not by itself guarantee that a model calls the tool before reading optional skills or project source. Add the persistent instructions below to establish the GoreGraph-first workflow.

Use goregraph mcp --expert-tools only for explicit manual diagnostics or legacy exploration. Expert tools are not part of the normal AI workflow.

Prepare and refresh the local index

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

goregraph version

Generate the index from the project or GoreGraph workspace root:

cd /path/to/project-or-workspace
goregraph scan .

scan builds both the agent and dashboard projections. To generate only the projection used by task_context, run:

goregraph build agent .

The MCP server intentionally does not scan automatically. Once enabled by the user, the watcher refreshes the agent index and dashboard after source changes; agents do not run update or build commands for this. If the watcher is stopped, the outputs remain at their last generated state. Users can refresh manually:

goregraph update . --target all

goregraph update scans the selected project again; it does not process only changed files. --target all shares one source extraction between the agent index and dashboard, keeping both current. Use --target agent only when the dashboard does not need refreshing. Runtime depends on project size and analysis work. In multi-project workspaces, use goregraph workspace update . --target all: it checks file content and skips unchanged projects, but fully rebuilds each changed project.

An optional local watcher can keep both projections current without an agent:

goregraph watch start .                 # background; first start asks about login autostart
goregraph watch status .                # running and autostart are separate
goregraph watch stop .                  # stop now; keeps the autostart choice
goregraph watch autostart off .         # remove future login startup

Recognized workspace roots are watched in workspace mode automatically; use --workspace for a flat or otherwise unrecognized workspace. watch status shows the output being updated and warns if an older project-mode watcher is pointed at a recognized workspace. Stop that watcher, then start it again with --workspace to switch modes. Installation never starts the watcher or enables autostart. The same commands work on Windows, macOS, and Linux; login autostart is opt-in and user-specific. The watcher checks selected file contents every few seconds, coalesces saves, and runs the existing project or workspace update for agent index and dashboard. It does not run tests or application code. An already open static dashboard may need a browser reload. See the watcher design and platform behavior.

Each task_context call should pass the active project or workspace root explicitly. This avoids depending on the working directory from which an MCP client launches the local process.

Codex — recommended

Codex is the recommended MCP client for GoreGraph. The Codex desktop app, CLI, and IDE extension share the same local MCP configuration. Register GoreGraph once:

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. Codex then starts and stops goregraph mcp automatically for its sessions; do not run a second MCP process manually.

Alternatively, add the server to ~/.codex/config.toml:

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

The desktop app also supports Settings → MCP servers → Add server. Select STDIO, use goregraph as the command, add mcp as the argument, save, and restart Codex. See the official Codex MCP documentation for current client-specific configuration options.

Claude Code

claude mcp add --transport stdio --scope user goregraph -- goregraph mcp
claude mcp list

Inside Claude Code, /mcp shows the connection and the task_context tool. Claude Code starts the local process when needed. A team can instead commit a project-scoped .mcp.json; see the official Claude Code MCP documentation.

Claude Code reads CLAUDE.md, not AGENTS.md. To keep one shared instruction source, add this project-root CLAUDE.md:

@AGENTS.md

Claude Code expands that import at session start. Additional Claude-specific instructions may follow it.

GitHub Copilot CLI

copilot mcp add goregraph -- goregraph mcp
copilot mcp list

Copilot CLI then starts the server automatically and can use task_context when it is relevant or explicitly requested. The configuration is stored in ~/.copilot/mcp-config.json. See the official Copilot CLI MCP documentation.

GitHub Copilot in VS Code

For repository-local configuration, create .vscode/mcp.json:

{
  "servers": {
    "goregraph": {
      "command": "goregraph",
      "args": ["mcp"]
    }
  }
}

Save the file, select Start above the server definition, and approve the workspace trust prompt. In Copilot Chat, select Agent mode and use the tools button to verify that goregraph exposes task_context. VS Code retains the configuration and starts the local server for later sessions. See the official GitHub Copilot MCP guide.

Focused source follow-up

Normal adaptive MCP context prioritizes the selected local call chain, including helpers in the same file, before related supporting evidence. Existing token, file, and source-coverage limits still apply; missing evidence remains explicit. The strict context and audit workflows retain their bounded contracts.

goregraph read returns optional next_request navigation when matching source or deferred files remain. Pass that object as the next read request for the same root only when those remaining results are relevant and authorized. It preserves independent search cursors and cumulative receipts, avoiding repeated source delivery. files[].citations gives exact newly delivered path:line or path:start-end references; disjoint ranges remain separate. These fields do not grant additional read permissions or prove that an investigation is complete.

Persistent GoreGraph-first instructions

Put the following block in the project-root AGENTS.md. For a personal Codex default across every repository, the same block can be placed in ~/.codex/AGENTS.md instead.

## GoreGraph-first source workflow

- For every coding task that requires repository knowledge, the first investigative action must be exactly one GoreGraph MCP `task_context` call.
- Before receiving and evaluating that Context Pack, do not read optional `SKILL.md` files, search or read project source, or start another analysis workflow. This also applies to debugging, code-review, and planning skills.
- Required loading of governing instructions and minimal discovery of the workspace root or GoreGraph tool may precede the call; this does not permit skill or source investigation.
- After evaluating the Context Pack, use optional skills only when needed for the remaining task. Skills must not override GoreGraph source-coverage, read-scope, or retry restrictions.
- For normal calls pass only `root` and `query`; omit `budget_tokens` and `max_files`. Use the active project or workspace root and the caller's technical problem and requested evidence scope, without inferred component responsibilities, tool policy, or output-format instructions.
- Treat returned `source_sections` as source already read. Never re-read or reconstruct delivered ranges; preserve exact range and receipt bookkeeping.
- Follow the returned protocol. With `protocol_version: adaptive-v2`, resolve material gaps using exact `verification_requests` first. If task-relevant evidence is still missing or `fallback_required` is true, stop context retrieval and use focused source discovery and bounded reads within the caller-authorized workspace. Start from supplied projects and identities; metadata is navigation, not proof of unread source. Do not bypass filesystem permissions, reader scope, redaction, or other safety restrictions.
- In adaptive source investigation, batch independent filename discovery and permitted `goregraph read` requests, carry forward read receipts, and read only still-missing evidence. Complete the requested production, configuration, and test inventories and verify behavior before claiming coverage. Do not declare a task complete merely because the initial pack is exhausted.
- For `strict-v1` (no `protocol_version`) or explicit audit mode, keep the bounded contract: complete coverage permits no additional indexed source reads; partial or missing coverage permits only exact project/path/ranges in `source_omissions`. Mark other details unknown. Audit mode never grants ordinary source fallback.
- Retry context only when `retry_allowed` is true, using exactly one supplied `retry_anchor` and the returned `context_id` as `previous_context_id`. Never repeat or expand the original query to force coverage.
- Low confidence or an unreliable production entrypoint means stop context retrieval; ordinary source fallback remains limited to the caller's task and permissions. Multiple roots are valid only for explicitly requested audit mode.
- If the agent index is missing or stale, use `goregraph doctor ` and `goregraph watch status ` to diagnose it. Do not run build or update commands; report the problem so the user can start or repair the watcher. Partial evidence alone is not a reason to rescan.
- After edits to indexed source, tests, or relevant configuration, do not run build or update commands. The user-enabled watcher refreshes the agent index and dashboard. Check `goregraph watch status ` when freshness matters, and report a stopped watcher, an error, or stale output instead of updating it yourself.
- Do not use specialist GoreGraph queries or expert MCP tools during the normal workflow.

Instruction files guide model behavior; they are not a hard technical gate. GoreGraph does not intercept ordinary file reads performed by an AI client. Keep the instruction concise and verify that the client loaded it. Check the first investigative action in normal sessions with the usual skills and settings enabled: it must be task_context, before any optional skill or source read. Explicitly name task_context in a prompt when diagnosing a new client setup.

Client instruction-file support differs:

Codex: project AGENTS.md, or ~/.codex/AGENTS.md for a personal global default.
Claude Code: project CLAUDE.md; import the shared file with @AGENTS.md. Personal global instructions belong in ~/.claude/CLAUDE.md.
GitHub Copilot: current VS Code and Copilot CLI versions support AGENTS.md. For the broadest compatibility across Copilot surfaces, put the same GoreGraph block in .github/copilot-instructions.md as well. Avoid conflicting copies.

Open the indexed project as the active workspace and test with a request such as:

Use GoreGraph task_context first to identify the current implementation path,
affected files, and relevant tests for this task.

Other MCP clients and cloud agents

For another local MCP-capable client, register a stdio server whose command is goregraph and whose argument list is ["mcp"], then add equivalent persistent instructions using that client's supported instruction mechanism.

The setup above is local. A cloud coding agent cannot reach the GoreGraph process or index on a developer workstation. To use GoreGraph in a cloud agent, the cloud environment must install the binary, obtain the source, build or restore a current agent index, and start goregraph mcp there. Do not point a cloud agent at a workstation-local stdio configuration.

If a client cannot connect to the server, verify the executable and registration:

goregraph version
codex mcp list       # Codex
claude mcp list      # Claude Code
copilot mcp list     # GitHub Copilot CLI

After installing GoreGraph or changing PATH, close and restart the affected terminals, IDEs, and AI clients before testing the 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  --query "" --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 "" 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 ; 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.

Local 1.4.1 development follow-up

The reader auto-paging follow-up from September 11, 2026 records a newer local development experiment, separate from the controlled release comparison above:

Measurement	Saved reference without GoreGraph	Successful third GoreGraph run
Effective tokens	165,839	79,464
Runtime, seconds	600.300493	505.816309
Static core criteria met	12/12	12/12

The documented reductions are 52.08% effective tokens and 15.74% runtime. The assisted run also found 7/7 required test identities, completed 14 commands without a failed GoreGraph command, and delivered no repeated source rows in the verified read outputs.

The tested binary was a local 1.4.1 development build, labeled d67d1f4ab3c3-dirty, built at 2026-09-11T15:09:29Z. Sharing the version number with the current release does not establish that the tested binary and the released binary are identical. The saved reference was not rerun, and the two preceding diagnostic runs had remaining command or coverage failures. This is one successful run on one frozen workspace, not a matched multi-run median or a result that can be combined with the earlier 85.92% release benchmark.

Effective tokens mean input tokens minus cached input tokens plus output tokens. They are not total tokens or a monetary cost measure; cached tokens are not universally free. Generated goregraph-out/ indexes and Context Pack estimated_tokens describe analysis artifacts or response budgets, not measured end-to-end token savings.

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.

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.

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

Measured token use

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.

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

1.4.3 — Unreleased

The development source version is 1.4.3. No release or tag has been created for this version; v1.4.2 remains the published release.

An optional local watcher now refreshes the agent index and dashboard after source changes. It starts only on request; login autostart is a separate per-user choice on Windows, macOS, and Linux.

1.4.2 — Workspace Explorer

Version 1.4.2 makes the redesigned Workspace Explorer the default offline dashboard.

Installation

Source version: GoreGraph 1.4.3 with output Schema 3.

Winget Windows — recommended

Winget is the recommended installation method on Windows. GoreGraph is available from the public Winget source under the stable package ID GoreCode.GoreGraph:

winget install --id GoreCode.GoreGraph --exact --source winget
goregraph version

Upgrade an existing installation with:

winget upgrade --id GoreCode.GoreGraph --exact --source winget

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 — alternative

Scoop is an alternative when Winget cannot be used. For the normal per-user installation, open a regular, non-administrative PowerShell and run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

irm get.scoop.sh -OutFile install.ps1
.\install.ps1 -RunAsAdmin
Remove-Item .\install.ps1

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 installation

Windows

Download the current Windows x86-64 archive directly:

Download goregraph_Windows_x86_64.zip

This link currently downloads the published 1.4.2 archive. A ready-to-use 1.4.3 Windows executable can be linked here after its binary asset is published.

Extract the ZIP into a stable directory, for example %LOCALAPPDATA%\Programs\GoreGraph\bin, and place goregraph.exe directly in that directory. Then add the directory to your user PATH:

Open Start and search for Edit environment variables for your account.
Under User variables, select Path, choose Edit, then New.
Add the directory that contains goregraph.exe and confirm all dialogs.
Close and reopen PowerShell, Command Prompt, your IDE, and Codex.

Verify from the new terminal:

Get-Command goregraph
goregraph version

Running .\goregraph.exe version inside the extraction directory alone does not prove that the PATH configuration works.

macOS and Linux

Download and extract the matching archive, then install the executable in a stable directory. A per-user location that does not require administrator rights is ~/.local/bin:

mkdir -p "$HOME/.local/bin"
install -m 0755 goregraph "$HOME/.local/bin/goregraph"

Ensure that directory is on PATH. On macOS with the default Z shell, add the following line to ~/.zshrc; on Linux, add it to ~/.profile or your shell's equivalent startup file:

export PATH="$HOME/.local/bin:$PATH"

Open a new terminal, then verify:

command -v goregraph
goregraph version

For a system-wide installation, /usr/local/bin is commonly already on PATH:

sudo install -m 0755 goregraph /usr/local/bin/goregraph

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 an archive, follow the manual installation steps above so the executable is available from every project directory.

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/`

For human exploration:

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

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 .

For an AI coding task:

goregraph build agent .
goregraph context . --query "" --budget-tokens 4000 --max-files 12

Call goregraph context . --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 ; never repeat or expand the original task.
Do not use specialist GoreGraph queries or expert MCP tools.

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

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 .

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]

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 .

goregraph workspace build all . --workspace .

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.

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: --format markdown --limit 20
goregraph query . symbol-api-consumers --query symbol: --format json --limit 20
goregraph query . symbol-explain --query usage: --detail full --format markdown --limit 20

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  [path]

goregraph scan

Compatibility alias for goregraph build all .

goregraph scan  --no-update-gitignore

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

goregraph scan  --no-workspace

Build both project projections and skip workspace discovery/reconciliation.

goregraph scan  --workspace

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]

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

goregraph context  --query  [--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

Print /goregraph-out/dashboard/report.md.

goregraph query

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

goregraph explain

Print indexed context for a file path or symbol name.

goregraph doctor

Check generated output health without scanning.

goregraph workspace status

goregraph workspace scan-missing

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  --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  [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]

goregraph workspace scan-all

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]

goregraph workspace clean

goregraph workspace diff --before  --after

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

goregraph workspace explain

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

goregraph workspace path --from  --to

Find a directed path between two generated workspace targets.

goregraph workspace impact --changed-file

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

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

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.

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

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.

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.

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.

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 integration

What MCP is and what GoreGraph exposes

reads the existing agent index;
does not scan or execute project code;
does not modify project files;
does not open a network port;
is started and stopped automatically by the configured AI client.

Use goregraph mcp --expert-tools only for explicit manual diagnostics or legacy exploration. Expert tools are not part of the normal AI workflow.

Prepare and refresh the local index

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

goregraph version

Generate the index from the project or GoreGraph workspace root:

cd /path/to/project-or-workspace
goregraph scan .

scan builds both the agent and dashboard projections. To generate only the projection used by task_context, run:

goregraph build agent .

goregraph update . --target all

An optional local watcher can keep both projections current without an agent:

goregraph watch start .                 # background; first start asks about login autostart
goregraph watch status .                # running and autostart are separate
goregraph watch stop .                  # stop now; keeps the autostart choice
goregraph watch autostart off .         # remove future login startup

Each task_context call should pass the active project or workspace root explicitly. This avoids depending on the working directory from which an MCP client launches the local process.

Codex — recommended

Codex is the recommended MCP client for GoreGraph. The Codex desktop app, CLI, and IDE extension share the same local MCP configuration. Register GoreGraph once:

codex mcp add goregraph -- goregraph mcp
codex mcp list

Alternatively, add the server to ~/.codex/config.toml:

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

Claude Code

claude mcp add --transport stdio --scope user goregraph -- goregraph mcp
claude mcp list

Claude Code reads CLAUDE.md, not AGENTS.md. To keep one shared instruction source, add this project-root CLAUDE.md:

@AGENTS.md

Claude Code expands that import at session start. Additional Claude-specific instructions may follow it.

GitHub Copilot CLI

copilot mcp add goregraph -- goregraph mcp
copilot mcp list

GitHub Copilot in VS Code

For repository-local configuration, create .vscode/mcp.json:

{
  "servers": {
    "goregraph": {
      "command": "goregraph",
      "args": ["mcp"]
    }
  }
}

Focused source follow-up

Persistent GoreGraph-first instructions

Put the following block in the project-root AGENTS.md. For a personal Codex default across every repository, the same block can be placed in ~/.codex/AGENTS.md instead.

## GoreGraph-first source workflow

- For every coding task that requires repository knowledge, the first investigative action must be exactly one GoreGraph MCP `task_context` call.
- Before receiving and evaluating that Context Pack, do not read optional `SKILL.md` files, search or read project source, or start another analysis workflow. This also applies to debugging, code-review, and planning skills.
- Required loading of governing instructions and minimal discovery of the workspace root or GoreGraph tool may precede the call; this does not permit skill or source investigation.
- After evaluating the Context Pack, use optional skills only when needed for the remaining task. Skills must not override GoreGraph source-coverage, read-scope, or retry restrictions.
- For normal calls pass only `root` and `query`; omit `budget_tokens` and `max_files`. Use the active project or workspace root and the caller's technical problem and requested evidence scope, without inferred component responsibilities, tool policy, or output-format instructions.
- Treat returned `source_sections` as source already read. Never re-read or reconstruct delivered ranges; preserve exact range and receipt bookkeeping.
- Follow the returned protocol. With `protocol_version: adaptive-v2`, resolve material gaps using exact `verification_requests` first. If task-relevant evidence is still missing or `fallback_required` is true, stop context retrieval and use focused source discovery and bounded reads within the caller-authorized workspace. Start from supplied projects and identities; metadata is navigation, not proof of unread source. Do not bypass filesystem permissions, reader scope, redaction, or other safety restrictions.
- In adaptive source investigation, batch independent filename discovery and permitted `goregraph read` requests, carry forward read receipts, and read only still-missing evidence. Complete the requested production, configuration, and test inventories and verify behavior before claiming coverage. Do not declare a task complete merely because the initial pack is exhausted.
- For `strict-v1` (no `protocol_version`) or explicit audit mode, keep the bounded contract: complete coverage permits no additional indexed source reads; partial or missing coverage permits only exact project/path/ranges in `source_omissions`. Mark other details unknown. Audit mode never grants ordinary source fallback.
- Retry context only when `retry_allowed` is true, using exactly one supplied `retry_anchor` and the returned `context_id` as `previous_context_id`. Never repeat or expand the original query to force coverage.
- Low confidence or an unreliable production entrypoint means stop context retrieval; ordinary source fallback remains limited to the caller's task and permissions. Multiple roots are valid only for explicitly requested audit mode.
- If the agent index is missing or stale, use `goregraph doctor ` and `goregraph watch status ` to diagnose it. Do not run build or update commands; report the problem so the user can start or repair the watcher. Partial evidence alone is not a reason to rescan.
- After edits to indexed source, tests, or relevant configuration, do not run build or update commands. The user-enabled watcher refreshes the agent index and dashboard. Check `goregraph watch status ` when freshness matters, and report a stopped watcher, an error, or stale output instead of updating it yourself.
- Do not use specialist GoreGraph queries or expert MCP tools during the normal workflow.

Client instruction-file support differs:

Codex: project AGENTS.md, or ~/.codex/AGENTS.md for a personal global default.
Claude Code: project CLAUDE.md; import the shared file with @AGENTS.md. Personal global instructions belong in ~/.claude/CLAUDE.md.
GitHub Copilot: current VS Code and Copilot CLI versions support AGENTS.md. For the broadest compatibility across Copilot surfaces, put the same GoreGraph block in .github/copilot-instructions.md as well. Avoid conflicting copies.

Open the indexed project as the active workspace and test with a request such as:

Use GoreGraph task_context first to identify the current implementation path,
affected files, and relevant tests for this task.

Other MCP clients and cloud agents

If a client cannot connect to the server, verify the executable and registration:

goregraph version
codex mcp list       # Codex
claude mcp list      # Claude Code
copilot mcp list     # GitHub Copilot CLI

After installing GoreGraph or changing PATH, close and restart the affected terminals, IDEs, and AI clients before testing the 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  --query "" --budget-tokens 4000 --max-files 12

Call goregraph context . --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 ; never repeat or expand the original task.
Do not use specialist GoreGraph queries or expert MCP tools.

Agent workflow skills and plugins

Agent context benchmark and release gate

Local 1.4.1 development follow-up

The reader auto-paging follow-up from September 11, 2026 records a newer local development experiment, separate from the controlled release comparison above:

Measurement	Saved reference without GoreGraph	Successful third GoreGraph run
Effective tokens	165,839	79,464
Runtime, seconds	600.300493	505.816309
Static core criteria met	12/12	12/12

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

License

Apache-2.0. See LICENSE.

GoreGraph GoreCode

README

GoreGraph

Measured token use

What GoreGraph does

1.4.3 — Unreleased

1.4.2 — Workspace Explorer

Installation

Winget Windows — recommended

Homebrew macOS/Linux

Scoop Windows — alternative

Manual installation

Windows

macOS and Linux

GitHub Releases

Quick Start

Project or workspace build?

Update source safely before scanning

Manual compatibility queries

Explore exact classes and symbols

Commands

Language Coverage

API integration depth

Output Files

MCP integration

What MCP is and what GoreGraph exposes

Prepare and refresh the local index

Codex — recommended

Claude Code

GitHub Copilot CLI

GitHub Copilot in VS Code

Focused source follow-up

Persistent GoreGraph-first instructions

Other MCP clients and cloud agents

Exclusions

Generated Output .gitignore

Configuration

Explain Context

Compact task context

Agent workflow skills and plugins

Agent context benchmark and release gate

Local 1.4.1 development follow-up

Security Model

License

GoreGraph GoreCode

README

GoreGraph

Measured token use

What GoreGraph does

1.4.3 — Unreleased

1.4.2 — Workspace Explorer

Installation

Winget Windows — recommended

Homebrew macOS/Linux

Scoop Windows — alternative

Manual installation

Windows

macOS and Linux

GitHub Releases

Quick Start

Project or workspace build?

Update source safely before scanning

Manual compatibility queries

Explore exact classes and symbols

Commands

Language Coverage

API integration depth

Output Files

MCP integration

What MCP is and what GoreGraph exposes

Prepare and refresh the local index

Codex — recommended

Claude Code

GitHub Copilot CLI

GitHub Copilot in VS Code

Focused source follow-up

Persistent GoreGraph-first instructions

Other MCP clients and cloud agents

Exclusions

Generated Output .gitignore