TokenCap

Website · Docs · Downloads · Benchmarks · GitHub

AI coding agents waste tokens re-discovering your codebase. TokenCap stops that.

TokenCap gives each AI coding session focused, ranked repository context instead of making the model rediscover the codebase from scratch. It builds locally, enforces a budget, and writes host-aware entry points for the tools your team already uses.

Website | Install | Benchmarks

Quick Start

npm install -g tokencap
tokencap make --full

Requirements: Node.js 18+ and Git.

Measured Results

TokenCap was benchmarked across three open-source repositories, five tasks per repository, for 15 measured data points. Token counts use js-tiktoken; estimated cost uses GPT-4o input pricing at $2.50 per million tokens.

| Repository | Size | Files | Naive context | TokenCap context | Reduction | | --- | --- | ---: | ---: | ---: | ---: | ---: | | fastify-example-todo | Small | 18 | 12,183 tokens | 8,275 tokens | 1.5x | | full-stack-fastapi-template | Medium | 195 | 146,702 tokens | 60,051 tokens | 2.4x | | hoppscotch | Large | 1,749 | 2,301,419 tokens | 70,685 tokens | 32.6x |

Across the measured tasks, a 820,101-token naive context was reduced to a 46,337-token TokenCap capsule: 12.2x fewer tokens and 94% lower estimated input cost, without changing the task answer.

Full methodology and published results are available at tokencap.vansharora.app.

Full methodology and raw data: benchmark results Reproduce: node benchmarks/run.js

• A managed repository capsule at .tokencap/snapshot.md.
• Graph and architecture intelligence under .tokencap/graph/.
• Current project memory under .tokencap/memory/.
• Machine-readable token savings at .tokencap/savings.json.
• Small pointer files for supported AI coding hosts, each directing the host to .tokencap/agent/START_HERE.md.

The capsule is not a repository dump. TokenCap ranks the files that matter for the current repository state, applies the configured budget, and preserves the most relevant signal for the next task.

Repository
  |
  +-- tokencap make --full
        |
        +-- rank files by recency, importance, and dependency reach
        +-- apply the context budget
        +-- generate project intelligence in .tokencap/
        +-- write host entry points and savings data

Current Version (v2.2.0) — Change & Collaboration

TokenCap turns a local change into an evidence-backed review packet:

tokencap analyze review
tokencap analyze review --base main
tokencap analyze ownership --history

Review packets include bounded base-ref symbol evidence, caller candidates, test-file association hints, and relevant Constitution/ADR context. Ownership and churn analysis is explicitly opt-in. Everything stays local: TokenCap does not post to Git providers, assign reviewers, or create commits.

For previous version release notes (v1.x, v2.0, v2.1), see the Changelog or Release History.

Agent Host Support

tokencap mcp --init --client <host> records one selected host. Later builds write only that host's pointer file and never overwrite an existing file. Without a selected host, builds create no editor-specific pointer.

| File | Host when selected | | ----------------------------------- | ------------------------------------------- | | AGENTS.md | Codex, Antigravity, OpenCode, VS Code Codex | | CLAUDE.md | Claude Code | | .cursor/rules/tokencap.md | Cursor | | .windsurf/rules/tokencap.md | Windsurf | | .clinerules/tokencap.md | Cline / Roo Code | | .github/copilot-instructions.md | GitHub Copilot | | .kiro/steering/tokencap.md | Kiro |

Skip pointer generation with --no-pointers.

VS Code and Plugins

The extension uses the TokenCap logo in its Marketplace card and provides commands to refresh Agent, Brain, Graph, and Memory intelligence independently. Its auto-capture mode refreshes the complete generated intelligence set after a saved source change.

To install the packaged local build while the Marketplace listing is being prepared:

code --install-extension .\tokencap-2.2.0.vsix

The source bundle also includes Codex and Claude Code integrations:

.\scripts\install-plugins.ps1

After it completes, run tokencap make --full in a project. Codex receives the TokenCap Context skill; Claude Code receives the TokenCap MCP integration and workflow skills. See the documentation for host-specific details.

Security and Privacy

• Local-first: no telemetry, analytics, or remote calls during normal operation. tokencap upgrade is the only command that contacts the network.
• Secret redaction: every file read passes through centralized redaction before it becomes output.
• Atomic writes: savings data and caches use temporary-file replacement to avoid partial reads.
• No overwrites: host pointer files are not replaced when they already exist.

Further reading

| Document | Contents | | ----------------------------------------- | --------------------------------------------------- | | Setup & Quickstart | Full installation, IDE wiring, MCP server setup | | Documentation | All commands (incl. impact), languages, frontend intelligence | | Benchmarks | Raw benchmark data, methodology, reproduction steps | | Changelog | Complete version history |

License

MIT