TokenGraph

TokenGraph is a local-first MCP plugin for Codex and Claude Code that helps coding agents spend less context rediscovering a repository. It indexes a trusted workspace locally, then routes agents through compact, task-scoped views of code, SQL, documentation, memories, and noisy tool output before broad raw-file reads.

• Local and self-contained: no cloud index, embeddings service, telemetry, paid external service, or OpenAI/Anthropic API key.
• Task-scoped: agents retrieve focused project maps, plans, summaries, failure traces, and exact source slices instead of dumping an entire index into context.
• Trust-bounded: the host must identify the workspace; installed plugin launches fail closed instead of trusting an arbitrary path.
• Evidence-led: deterministic benchmarks and reviewed real-host traces are checked into the repository, while automatic routing stays in shadow mode until every promotion gate passes.

Current source version: 0.23.1 | Runtime: Node.js 22 or newer | Open source under the Apache License 2.0. The downloadable version is the one shown by the GitHub Latest release badge; a source version is not a published release asset.

The recommended path adds this GitHub repository as a plugin marketplace and installs the committed, self-contained package under release/tokengraph; users do not run pnpm install or build TypeScript.

codex plugin marketplace add Mujadarah/TokenGraph
codex plugin add tokengraph@tokengraph
codex plugin list --json

Codex must provide a trusted project root. Each MCP request names its active project and thread; TokenGraph accepts that metadata only when it matches the reviewed lifecycle-hook attestation for the same task, so one global installation works across simultaneous repositories without a machine-wide workspace variable. If hooks are disabled or untrusted and the client does not support MCP Roots, use the compatibility fallback before starting Codex:

$env:TOKENGRAPH_WORKSPACE_ROOT=(Get-Location).Path
codex

TOKENGRAPH_WORKSPACE_ROOT="$PWD" codex

Start a new task after installation or configuration changes so SessionStart can attest that task's host working directory. Review and trust TokenGraph's hook definition when Codex prompts. During development launches, the process working directory is the final host-derived fallback only when the server is not running from an installed plugin directory. Installed plugin launches deliberately stay blocked rather than trusting an arbitrary tool argument.

Run these commands inside Claude Code:

/plugin marketplace add Mujadarah/TokenGraph
/plugin install tokengraph@tokengraph
/reload-plugins

Non-interactive equivalents are also available:

claude plugin marketplace add Mujadarah/TokenGraph
claude plugin install tokengraph@tokengraph

Claude Code forwards CLAUDE_PROJECT_DIR to TokenGraph automatically.

For a published version, download its tokengraph-<version>.zip asset from the GitHub releases page and extract it. The extracted directory is a standalone marketplace root containing both host catalogs and the installable tokengraph/ plugin. A source version is not downloadable until its tag and release asset are published.

codex plugin marketplace add C:\path\to\tokengraph-<version>
codex plugin add tokengraph@tokengraph

claude plugin marketplace add /path/to/tokengraph-<version>
claude plugin install tokengraph@tokengraph

Use a generic placeholder or your own local path; never publish a machine-specific profile path.

Ask the agent:

Use TokenGraph to check setup, index this project, and plan compact context before reading raw files.

The expected sequence is:

1. tokengraph_setup reports ready and identifies the host-provided trust source.
2. For planning, tokengraph_prepare_context indexes or refreshes the workspace and returns a compact task id plus plan. For direct query, compression, recall, or analysis, omit taskId on the first intent call; it starts the task and returns the task id.
3. Reuse that exact task id. After ready setup, root can be omitted when host workspace resolution remains stable; otherwise use only the trusted root returned by setup.
4. Call tokengraph_task_report({ taskId }) after successful implementation and verification. Its compact default returns status, taskId, the canonical savings footer, and reportingStatus; request verbose mode only for diagnostics, or use pause for unfinished work.

A paused task id is terminal. Resume with tokengraph_prepare_context or a direct intent call that omits taskId; never send later calls with the paused id.

The setup diagnostic never grants filesystem trust. If it reports blocked, follow its recovery steps and restart or reload the host.

TokenGraph exposes eight compact intent-level tools by default and 42 tools on the opt-in full compatibility surface. Nine focused skills cover:

• setup diagnosis and workspace-safe indexing;
• project maps, symbol/import search, and context planning;
• PostgreSQL and Supabase migration/RLS summaries;
• local wiki and memory lifecycle workflows;
• architecture rules, failure tracing, and regression risk;
• context, logs, builds, tests, diffs, and SQL compression;
• token-saving profiles and release-package auditing.

See the source plugin guide for the complete tool catalog.

TokenGraph indexes TypeScript, JavaScript, SQL, Markdown, Python, Go, Rust, and Java by default. Pinned Tree-sitter WASM grammars for the four polyglot languages run locally with bounded resources; set parser.polyglotEnabled to false in the project's .tokengraph/config.json when a project needs the kill switch.

Every measured task has one canonical completion footer backed by a task ledger. JSON-only MCP successes return one serialized JSON TextContent item; tokengraph_export_project_map remains the documented resource-link exception. Diagnostic token estimates identify their baseline in the response: full-index-dump, task-files-and-memories, provided-context, or provided-output. They are not substitutes for the execution-inclusive benchmark. Wiki and memory updates use source-linked review-before-apply proposals: listing and proposing do not mutate derived knowledge. Approval requires at least one workspace-relative path whose canonical LF-normalized SHA-256 fingerprint is revalidated; stable logical ids remain expiring, attested/unverifiable snapshots and never become current or high-confidence. ID-only and legacy bare-fingerprint proposals cannot be approved, and stale or expired proposals fail.

Routing decisions expose the frozen expectedBenefit enum none | low | medium | high: bypass and fail-open paths use none, Stage 0 activation uses the recommended medium, Stage 1 indexed activation uses high, and low remains reserved. Routing stays in shadow mode unless reviewed real-host evidence passes every promotion gate.

The checked-in deterministic fixture benchmark preserves 100% of critical constraints, has zero critical false negatives, and reaches 100% required-file recall. Three bounded tasks bypass at Stage 0 and are not booked as savings. Across the 27 activated tasks, the primary execution-inclusive median is +174.5 estimated tokens, the nearest-rank p25 is +40.5, and 22 tasks (81.5%) are non-negative, so the frozen deterministic release gate passes. Four edit/debug tasks charge one hash-validated exact source slice each, totaling 711 estimated tokens. The baseline is category-appropriate: minimal expert raw reads for code, SQL, risk, memory, and release tasks, and real noisy runner captures for debugging and compression. Memory/wiki remains negative in three of four fixtures and change risk in two of four; negative tails are not hidden. Every fixture category still has fewer than 10 observations, so calibration confidence remains low. These fixture estimates are not provider billing counts, autonomous-agent patch-quality evidence, or universal Codex/Claude proof.

Real-host evidence is reported separately from fixture economics. Reviewed schema-v3 campaigns cover TokenGraph, mattpocock/ts-reset, and imbhargav5/nextbase-nextjs-supabase-starter: fifteen counterbalanced ON/OFF pairs and thirty accepted traces across three repositories and three categories. The multi-repository B6 coverage target is met, but routing promotion and enforcement remain disabled because not all frozen sample, performance, resource, and router gates passed. Routing stays in shadow mode; B7 polyglot indexing is an independent local parser capability and is active by default. See the TokenGraph manifest and report, the ts-reset manifest and report, and the Nextbase manifest and report.

Lifecycle hooks are cooperative automation. Users must review and trust them; they can be disabled, and interrupts, process termination, StopFailure, or API failure do not run normal completion enforcement. Missing or corrupt hook state fails open with a warning.

• Codex installation and runtime
• Claude Code installation and runtime
• Generic MCP clients
• Contributing
• Security reporting
• Project governance
• Privacy and local storage
• Security and workspace trust
• Release installation
• Benchmark methodology and claims
• Release history and roadmap

• Setup is blocked: call tokengraph_setup and apply the host-specific recovery steps.
• Plugin is missing: inspect codex plugin marketplace list and codex plugin list --json, or /plugin in Claude Code.
• Tools are missing after install: start a new Codex task or run /reload-plugins in Claude Code.
• Context is stale: start a fresh task and rerun tokengraph_prepare_context; it refreshes the index before planning.
• Release ZIP will not install: add the extracted bundle root, not its nested tokengraph/ directory.

Implementation lives under plugins/tokengraph/. The committed release/tokengraph/ directory is generated output.

cd plugins/tokengraph
pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm smoke -- --root . --json
pnpm validate:plugin
pnpm package:plugin -- --json
pnpm package:plugin -- --release --json

The default package command creates artifacts/tokengraph-<version>/ and a deterministic, standalone artifacts/tokengraph-<version>.zip.

Indexes, configuration, wiki pages, token events, rules, and memories stay under .tokengraph/ in the trusted workspace. Token savings are estimates, and TokenGraph does not replace code review or guarantee correctness.

TokenGraph is open-source software licensed under the Apache License 2.0. The NOTICE file contains the project attribution that must accompany redistributed copies. Contributions accepted into this repository are licensed on the same terms.