Install TokenCap globally with npm:

npm install -g tokencap

Then run from your JS/TS project root:

tokencap make

This generates three files in your project root:

• TOKENCAP.md — compressed project snapshot (all languages)
• TOKENCAP_GRAPH.md — dependency graph (JS/TS projects)
• TOKENCAP_MEMORY.md — developer context memory (all projects)

For VS Code, install the TokenCap extension from the marketplace (publisher: VanshArora21). It auto-captures on every file save.

Create a .tokencap.json file in your project root to customize behavior:

{
  "profile": "balanced",
  "outputPath": "TOKENCAP.md",
  "maxFiles": 90,
  "maxSourceBytes": 220000,
  "maxFileBytes": 14000,
  "maxDiffBytes": 50000,
  "includeGitDiff": true,
  "includeFileContents": true,
  "excludePatterns": ["node_modules/**", "dist/**", "build/**", "coverage/**"],
  "redactSecrets": true
}

Configuration is resolved in the following priority order: defaults → profile overrides → .tokencap.json → CLI flags.

TokenCap ships with context profiles tuned for different AI models and use cases.

Select a profile via CLI flag or .tokencap.json:

tokencap make --profile claude-3-5-sonnet

TokenCap moves from simply generating full codebase snapshots to retrieving exactly what matters. Ask a natural language question or request context by topic keyword, and the retrieval engine finds the relevant files, performs graph BFS, filters by token budget, and generates a tailored AI prompt.

How it Works (Retrieval Engine)

Your question
  → Extract keywords ("auth", "login", "jwt")
  → Match to clusters (Authentication)
  → Score all files using Graph + Memory + Diff + Impact
  → BFS: find dependencies & dependents (up to 2 hops)
  → Rank by composite relevance score
  → Allocate token budget (default: 12,000)
  → Generate context.md + prompt.md

• Multi-Source Retrieval — Searches across your dependency graph (clusters, connections), developer memory (active tasks, decisions), git status (recent changes), and risk impact score to rank files by relevance.
• Auto-Mode Detection — Questions are parsed to auto-detect the retrieval intent. Keywords like "explain" auto-detect architecture mode, "review" or "verify" auto-detect review mode, and "debug" or "fix" auto-detect debug mode.
• Graph BFS Traversal — Traverses the dependency structure up to 2 hops from matching files to ensure all relevant helper modules, utilities, and parent controllers are included in the package.
• Token-Budgeted Output — Dynamically applies representation tiers (Full content, Structural outlines, AST summaries, or Reference Only) to fit the retrieved content into a strict token budget.

Ask about any part of your codebase

tokencap ask "How does authentication work?"
tokencap ask "Explain invoice generation"
tokencap ask "debug login redirect"           # Auto-detects debug mode
tokencap ask "review payment flow"             # Auto-detects review mode

Quick topic context

Generate topic-specific context manually using a keyword:

tokencap context auth
tokencap context payments
tokencap context dashboard

TokenCap scans all JS/TS source files and maps how they connect to each other.

tokencap graph

This generates TOKENCAP_GRAPH.md and exports graph data to .tokencap/graph/.

Graph Intelligence & Visualization Features

• Obsidian-Style Interactive Viewer (`--open`) — Opens a self-contained, dark-mode, three-panel graph viewer in your default browser. Features zoom, pan, hover highlights, local graph mode (showing a selected node + direct dependencies/dependents), cluster filtering, and a right-side node inspector panel showing metadata, risk, and impact.
• 13 Node Classifications — Categorizes files into route, api, component, controller, service, database, middleware, config, utility, hook, package, test, and unknown with distinct color representations.
• 4-Tier Risk Scoring — Assigns a CRITICAL, HIGH, MEDIUM, or LOW risk tier to each node based on connectivity, classification, and git modification status.
• Graph Presets — Simplifies running graph actions:
• --full — Runs JSON export, AI narrative summary, graph diff, and opens the HTML viewer in your browser (combines --json --ai --diff --open).
• --minimal — Exports only graph-data.json, nodes.json, and edges.json. No HTML, AI, or diff (fastest).
• --quiet — Runs in the background and prints only a clean summary statistics block.
• Cluster Detection — Automatically groups code files into logical modules: Authentication, Payments, Dashboard, Database, API, Frontend, Config, Testing, and Utilities.
• TOKENCAP.md Graph Summary — Injects a ## Project Graph Summary section containing key metrics (node/edge counts, high-risk files, clusters detected) into the main snapshot after every graph run.

Supported file extensions: .ts, .tsx, .js, .jsx, .mjs, .cjs

Import patterns parsed:

• import x from "./file"
• import { x } from "../file"
• export { x } from "./file"
• const x = require("./file")

Node classification:

Note: Only local relative imports are followed. External packages (react, lodash, etc.) are ignored.

Preserve your developer context across sessions.

Instead of a separate command, the context memory layer is automatically compiled whenever you run tokencap make.

This process:

1. Reads your developer notes from .tokencap-notes.md in your project root (auto-created if missing).

2. Combines them with live Git context (branch name + changed files).

3. Writes a structured TOKENCAP_MEMORY.md context file.

Edit `.tokencap-notes.md` directly:

## Current Task
Fix login redirect after successful authentication.

## Developer Intent
Improve auth flow without changing the DB schema.

## Known Issues
- Session sometimes not ready before redirect.

## Constraints
- Do not modify Prisma schema.

## Decisions Made
- Using server-side session validation.

## Next Steps
- Test login flow.
- Check middleware.

The Context Packing Engine is a budget-driven, importance-scoring compressor that fits codebases of any size into AI context windows. It intelligently selects and transforms codebase content based on topic relevance, import topology, git churn, and semantic importance, ensuring that the most relevant information is prioritized within the token budget.

Topic-Based Packing

You can generate Brain-scoped context packs tailored to specific clusters or topics:

tokencap pack auth
tokencap pack payments

When a topic is provided, the pack engine queries the Project Brain to boost relevance scores for files within that cluster, ensuring the generated pack is focused on the user's current area of interest.

Pack Modes

• `review` (Default) — Optimized for PRs and manual code reviews. Prioritizes recent git changes, main entry points, and high-impact dependencies.
• `debug` — Optimized for fixing bugs. Prioritizes stack trace locations, error handlers, and state management logic.
• `architecture` — Optimized for onboarding. Excludes implementation details, providing high-level structural outlines, interface definitions, and module manifests.
• `minimal` — A lightweight status report containing only git state, active tasks, and module-level summaries.

How it Compresses (Budget Engine)

TokenCap analyzes files and applies one of four representation tiers based on their semantic importance score:

• 🟢 Full Content: Critical files are written in full.
• 🟡 Structural Outline: Mid-importance files are trimmed to show only exported members, function signatures, and class definitions.
• 🟠 AST Summary: Low-importance files are summarized into small, token-dense structural descriptions.
• 🔴 Reference Only: Distant/utility files are listed as file paths to maintain context without consuming significant tokens.

Generate a pack with a custom token budget:

tokencap pack --mode debug --budget 30000

The Change Intelligence Engine goes beyond standard git diffs by analyzing changes semantically. It provides a deterministic, rule-based report outlining impact, risk, breaking changes, and testing suggestions.

tokencap diff

Key Capabilities

1. Semantic Layering — Classifies modified files into functional layers like Authentication, Payment, Database, API, Frontend, Security, etc.

2. Deterministic Risk Rating — Computes risk levels (LOW, MEDIUM, HIGH, CRITICAL) based on files touched, lines modified, database schema changes, or breaking change detections.

3. Breaking Change Scanning — Scans for common breaking patterns such as removed exports, function signature alterations, prisma field deletions, and .env modifications.

4. Endpoint Capture — Identifies added or modified HTTP routes/endpoints (e.g. Express, Next.js App Router) and suggests specific edge cases to test.

5. Prompt Generator — Produces ready-to-use markdown prompts for AI code review or PR summaries:

• --pr generates a condensed pull request description.
• --prompt generates a structured prompt guiding an LLM to review your changes.

Analyze staged changes or the last commit:

tokencap diff --staged
tokencap diff --last

TokenCap introduces the flagship Self-Loading Universal Context Layer in v1.0.0. By running the tokencap agent command, AI agents can automatically discover and load repository context without manual intervention.

Auto-Discovery Flow

Repository
  → tokencap agent
  → Generates AGENTS.md (root)
  → AI Agents automatically find and read AGENTS.md
  → Redirects to .tokencap/agent/START_HERE.md
  → AI loads onboarding instructions, paths, and manifests automatically

What gets generated

Running tokencap agent compiles a comprehensive set of onboarding files inside .tokencap/agent/ and creates an AGENTS.md entry point at your repository root:

• `AGENTS.md` (root) — AI auto-discovery entry point. Agents find this first and follow instructions to load the context.
• `START_HERE.md` — Full onboarding instructions that guide the AI on reading order, critical areas, high-risk files, and non-negotiable coding conventions.
• `allowed-context.json` — Topic-to-file-glob map guiding AI agents directly to relevant files for a task without performing a full repository scan.
• `model-instructions.md` — Generic model guidelines detailing codebase layouts, constraints, and instructions for any LLM.
• `context-manifest.json` — Machine-readable single source of truth containing version, project types, active clusters, critical files, and recommended reads.
• `agent-pack.md` — The complete paste-ready markdown payload aggregating stack, architecture, conventions, and rules.
• `agent.json` — Structured JSON representation of repository intelligence.

Command Options

• tokencap agent — Generates the full universal context layer and root AGENTS.md (default).
• --no-agents-file — Skips generating the root-level AGENTS.md file if you prefer to keep your repository root clean.
• --export <target> — Export rules directly to Cursor (.cursorrules), Windsurf, Cline, or Roo Code formats.
• Mode flags (--architecture, --rules, --skills) compile focused subsets of the onboarding files.

TokenCap introduces the Execution Contract in v1.1.0 to teach AI coding agents how to work — not just what to know. While context layers provide project intelligence, execution contracts ensure discipline and prevent agents from losing focus.

Auto-Discovery Flow

Repository
  → tokencap agent --execution
  → Generates .tokencap/agent/execution-contract/
  → 8 lifecycle files mapped to agent workflows
  → AI Agents read rules and track objectives in real-time

Lifecycle Files & Mappings

The Execution Contract compiles 8 specialized files under .tokencap/agent/execution-contract/, each mapped to a specific development phase:

Headline Feature — Scope Drift Detection

AI agents frequently expand the task scope without warning. TokenCap's Scope Drift Detection forces the agent to pause and explain its reasoning if it expands beyond the original objective (e.g. going from Authentication to Middleware to Database to Analytics):

Original Scope:   Authentication
Current Scope:    Authentication → Middleware → Database → Analytics
Drift Level:      HIGH

Expansion Reason: [required before continuing]

Minimal Solution First

Before creating new code, the agent must systematically evaluate existing solutions:

1. Configuration changes

2. Existing utilities

3. Existing components

4. Existing services

5. Installed dependencies

6. Platform capabilities

7. Pre-existing code patterns in the repository

Advisory vs Strict Mode

• tokencap agent --execution — advisory mode (default), providing soft guidance and preserving agent autonomy.
• tokencap agent --execution --strict — strict mode, enforcing scope gating checks and cluster boundaries.

TokenCap introduces the Repository Constitution in v1.2.0 to encode permanent engineering laws that AI coding agents must never violate, regardless of the current task. While context layers inform and contracts guide, constitutions enforce structural boundaries, schemas, security limits, and compliance.

Single Source of Truth — Constitution Graph

All rules are parsed and managed through an internal ConstitutionGraph before being rendered into multiple formats:

Analyzers
    ↓
Constitution Graph (Internal)
    ↓
Renderers
    ├── constitution.json      (Machine-readable)
    ├── constitution.md        (Human-readable summary)
    ├── constitution.yaml      (Structured export)
    ├── START_HERE.md          (AI entry point overview)
    └── Interactive HTML UI    (constitution-graph.html)

Lifecycle Files Generated

Running tokencap constitution or tokencap make compiles a comprehensive set of law sheets inside .tokencap/constitution/:

• `constitution.json` / `.yaml` — Enriched rules mapping categories, severities, confidence, and relationships.
• `constitution.md` — Plain-language summaries of laws, reasons, and failure results.
• `constitution-graph.html` — Interactive graph visualization of constraints and rules.
• `api-contracts.yaml` — API routes and stability contracts.
• `schema-invariants.yaml` — Database field protection rules.
• `architecture-laws.md` — High-level layout boundaries.
• `security-boundaries.md` — Cryptography, sanitization, and access rules.
• `compliance-rules.md` — PCI-DSS, GDPR, HIPAA, SOC 2 mandates.
• `critical-flows.md` — Multi-step transactional flows that cannot be broken.
• `constitution-history/` — Timestamped snapshot database of rules over time.

Severity Hierarchy

Rules are classified into severities to enforce strictness during verification:

• IMMUTABLE — Absolute laws (e.g. PCI compliance, password hashes). Violations cause immediate task abort.
• CRITICAL — High-importance rules. Requires override justification.
• HIGH — Common architectural limits.
• WARNING — Style or minor pattern suggestions.
• INFO — Pure metadata.

Manual Overrides

Define custom rules that cannot be automatically inferred in tokencap.constitution.yaml at your repository root:

rules:
  - id: CONST-BIZ-001
    severity: IMMUTABLE
    confidence: 1.0
    category: BusinessLogic
    description: "Subscription downgrade path must preserve all user data for 30 days."
    reason: "Legal requirement per Terms of Service §4.2"
    whatBreaks: "Immediate data deletion violates legal obligations."

Analyze once. Update only what changed.

Every time tokencap make ran before v1.3.0, it rebuilt the entire repository intelligence — graph, brain, constitution, agent files — from scratch. Even if a single file changed.

v1.3.0 ends that.

How It Works

tokencap make
      │
      ▼
Phase 1: Detect Changes
  SHA-256 hash comparison against .tokencap/cache/hashes.cache.json
  Git status cross-reference for rename detection
  mtime pre-filter for speed
      │
      ▼
Phase 2: Analyze Impact
  Map changed files → affected clusters (via knowledge.json)
  Propagate to dependent clusters (one level)
  If >60% clusters affected → full build (cheaper)
      │
      ▼
Phase 3: Walk Dependencies
  Bidirectional BFS on the dependency graph
  Forward walk: consumers of changed files
  Backward walk: providers of changed files (edge invalidation)
      │
      ▼
Phase 4: Selective Rebuild
  Graph:        patch only dirty nodes, prune ghost edges
  Brain:        update only affected clusters in knowledge.json
  Constitution: re-evaluate only impacted rules via getImpactedRules()
  Agent files:  update only sections referencing affected clusters
      │
      ▼
Phase 5: Update Cache
  Write .tokencap/cache/hashes.cache.json (atomic, with checksum)
      │
      ▼
Phase 6: Write Deltas + History
  .tokencap/delta/*.delta.json     ← what changed this run
  .tokencap/delta/history/         ← versioned snapshots (default: 10)

Delta Files

After every incremental build, TokenCap writes delta files that describe exactly what changed:

.tokencap/delta/
  changed-files.json         ← which files changed (added/modified/deleted/renamed)
  affected-clusters.json     ← which clusters need updating
  dirty-nodes.json           ← which graph nodes are stale
  brain.delta.json           ← clusters updated, clusters skipped
  graph.delta.json           ← nodes updated, nodes removed, nodes added
  constitution.delta.json    ← rules re-evaluated, rules unchanged
  agent.delta.json           ← agent sections updated

  history/
    brain.v14.delta.json     ← versioned snapshot (last 10 by default)
    graph.v14.delta.json
    constitution.v14.delta.json
    agent.v14.delta.json

AI agents consuming incremental updates receive only what changed — not the full repository intelligence.

Zero-Change Scenario

If nothing changed since the last build:

$ tokencap make
TokenCap: No changes detected. Intelligence is up to date.

Sub-second. No disk writes. No rebuilding.

Cache Integrity

The hash cache is validated with a SHA-256 checksum on every load. If the cache is corrupted, missing, or from an incompatible version, TokenCap automatically falls back to a full build — no manual intervention needed.

New CLI Flags

tokencap make                          # Incremental build (default — new in v1.3.0)
tokencap make --full                   # Force full rebuild (v1.2.0 behavior)
tokencap make --rebuild-brain          # Rebuild only the Brain knowledge base
tokencap make --rebuild-constitution   # Rebuild only the Constitution Engine
tokencap make --rebuild-graph          # Rebuild only the Dependency Graph
tokencap make --clean-cache            # Clear the incremental cache (next build = full)

Performance

Incremental Build Output Example

TokenCap: 3 file(s) changed — running incremental build...
  Changed: src/auth/jwt.js, src/payments/stripe.js +1 more
  Dirty nodes: 7, Clean nodes: 113
  Graph:               3 node(s) updated, 0 removed (41ms)
  Brain:               2 cluster(s) updated, 8 skipped (18ms)
  Constitution:        4 rules updated, 12 unchanged (9ms)
  Agent:               2 file(s) updated (6ms)

TokenCap Incremental Build Complete
──────────────────────────────────────────────────
Build type:          incremental
Duration:            74ms
Files changed:       3
  Added:             1
Clusters updated:    2
Clusters skipped:    8
  Changed:           Authentication, Payments
──────────────────────────────────────────────────
Delta files:         .tokencap/delta/

TokenCap thinks in clusters, not just files. The flagship Project Brain (tokencap brain) allows you to query any part of your codebase to get a unified intelligence view including files, risk levels, architecture, dependencies, review groups, recent changes, and git timeline — all from a single command.

How it Works

Your topic ("auth")
  → Load .tokencap/brain/knowledge.json   (built by tokencap make)
  → Fuzzy-match topic against cluster names and file paths
  → Resolve matching cluster + all intelligence views
  → Render to terminal in requested mode

Brain Modes

• Overview (Default) — Displays files, risk level, review group, recent changes, and architecture chain.
• Impact (`--impact`) — Shows affected file/feature count, critical files, and risk levels.
• Architecture (`--architecture`) — Renders the dependency chain (what this cluster depends on / is used by) as an ASCII map.
• Review (`--review`) — Shows files in the review group and the reason for grouping.
• Timeline (`--timeline`) — Lists Git commit history (date + message) for cluster files.
• Risk (`--risk`) — Pinpoints high-risk areas, reason, and affected files.
• Deps (`--deps`) — Lists all direct depends-on and used-by edges.

Example CLI Usage

tokencap brain auth                  # Full overview of auth cluster
tokencap brain payments --impact     # Impact analysis of payments changes
tokencap brain auth --architecture   # ASCII dependency chain
tokencap brain auth --timeline       # Git history timeline for auth
tokencap brain                       # Overview of all clusters with risk levels

TokenCap automatically redacts secrets before writing any file content to disk. Redaction is enabled by default (redactSecrets: true).

Patterns detected and redacted:

• OpenAI API keys: sk-... → [REDACTED_OPENAI_KEY]
• GitHub PATs: ghp_..., github_pat_... → [REDACTED]
• Slack tokens: xox... → [REDACTED]
• AWS access keys: AKIA... → [REDACTED]
• Google API keys: AIza... → [REDACTED]
• Bearer tokens (≥20 chars)
• Generic variable assignments: api_key=, token=, secret=, password=, passwd=, pwd=

To disable redaction (not recommended for shared snapshots):

{ "redactSecrets": false }

TokenCap introduces the Repository Intelligence Service (MCP) in v1.4.0 and Self-Maintaining MCP Intelligence in v1.5.0. Instead of re-reading generated markdown context files at the start of every AI session, AI hosts (Cursor, Claude Code, Windsurf, Cline, VS Code, Antigravity, Codex) can query live, local repository intelligence on demand.

1-Command Setup

tokencap serve --mcp --init

For host-specific flags, latency benchmarks, tool endpoint details, and diagnostics, view the dedicated [TokenCap MCP Guide](/mcp).

TokenCap v2.2.0 turns local code edits into evidence-backed review packets:

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

Review Packets

Review packets include bounded base-ref symbol evidence, caller candidates, test-file association hints, and relevant Constitution/ADR context.

• Base-Ref Comparisons — Compare uncommitted changes against HEAD~1, main, or any target branch.
• Caller Candidates — Uses AST symbol graphs to isolate direct callers of modified functions.
• Test Associations — Links modified source files with corresponding unit and integration test fixtures.
• Opt-In Ownership Signals — tokencap analyze ownership --history provides local Git churn and contributor distributions strictly as advisory context.
• Zero Remote Egress — Everything stays local under .tokencap/; TokenCap never posts to Git providers or assigns reviewers.

TokenCap v2.3.0 introduces Guided Change — deterministic refactoring engines, static test mapping, coverage report ingestion, and local feedback loops:

# Dry-run refactoring preview (default)
tokencap analyze refactor rename src/auth/token.js:validateToken checkToken
tokencap analyze refactor rm-dead src/util/helpers.js:unusedHelper

# Apply refactoring changes atomically
tokencap analyze refactor rename src/auth/token.js:validateToken checkToken --write

# Static Test Intelligence & Gap Analysis
tokencap analyze tests
tokencap analyze tests --gaps
tokencap analyze tests --coverage coverage/lcov.info

# Local Agent Feedback Loop
tokencap analyze feedback record --agent claude --outcome helped --task "refactor auth"
tokencap analyze feedback report

Guided Safe Refactoring

• Rename Across the Graph — Renames the symbol definition, non-aliased imports, and cross-file callers while maintaining byte-exact code preservation outside edit boundaries.
• Refuse on Doubt — Automatically halts with non-zero exit when detecting aliased imports, shadowing, collisions, or computed property accesses.
• Safe Dead Code Removal — Re-verifies all references before planning symbol deletion; strictly refuses on exported or entry-point symbols.

Test Intelligence & Gap Mapping

• Static Associations — Analyzes AST call graphs and test file conventions to map which test fixtures exercise specific symbols.
• Untested Symbol Gaps — Flags symbols called across the codebase that have zero matching test associations (--gaps).
• Read-Only Coverage Ingestion — Parses existing lcov or Istanbul JSON reports to associate symbol line ranges with execution coverage without running test suites.

Local Agent Feedback Loop

• Local Context Tracking — Records private feedback (helped, neutral, hurt) under .tokencap/feedback/log.json to monitor AI agent effectiveness.
• 100% Offline — Explicit local: true, telemetry: false guarantee with zero network egress.

TokenCap v2.4.0 extends language depth and adds schema and taint analysis:\n\n``bash\n# Full Tier-1 Go / Rust / Java impact analysis\ntokencap ask impact src/server/handler.go:ServeHTTP\ntokencap ask impact src/lib/auth.rs:validate_token\n\n# SQL & GraphQL schema extraction\ntokencap analyze schema\n\n# Static taint flow analysis (JS/TS)\ntokencap analyze taint\ntokencap analyze taint --file src/api/users.js\n\n# Vue / Svelte / Angular component intelligence\ntokencap analyze components src/components/\n\n\n### Full Tier-1 Go / Rust / Java\n\n- **Cross-File Resolution** — Resolves locally-defined, import-bound, single-exported-match, and repo-unique symbols across Go, Rust, and Java.\n- **Honest Unresolved Counts** — Overloaded or same-named symbols across files are explicitly reported as unresolved rather than guessed.\n\n### SQL & GraphQL Schema Intelligence\n\n- **Table & Type Extraction** — Finds tables from CREATE TABLE DDL and types from GraphQL type blocks.\n- **Code Link Candidates** — Heuristic code-to-schema links labeled as candidates, not authoritative.\n\n### Static Taint Flow Analysis (JS/TS)\n\n- **Source-to-Sink Tracking** — Tracks user inputs (req.body, req.query, process.env) to dangerous sinks (SQL, exec, fs writes).\n- **Sanitizer Modeling** — Known sanitizers clear taint; unknown functions named like sanitizers are conservatively non-sanitizing.\n- **Intra-procedural only** — Cross-function and cross-file flow is not tracked.\n\n### Vue / Svelte / Angular Component Intelligence\n\n- **SFC Parsing** — Reads defineProps / props: for Vue/Svelte; @Component` decorators for Angular.\n- Unresolved Count — Dynamic and computed tag names are counted, not resolved into edges.

TokenCap v2.6.0 powers the local loopback HTTP bridge with warm in-memory reuse, model-aware token budgeting, and detached daemon management, enabling browser extensions like the Chrome Companion to query project intelligence with sub-millisecond overhead and zero network egress:

# Start local loopback bridge
tokencap serve

# Run as detached background daemon
tokencap serve --daemon

# Stop running daemon
tokencap serve --stop

# Start with custom port and token
tokencap serve --port 4545 --token mytoken123

Bridge Contract v1 Endpoints

• `GET /health` — Server status and engine version.
• `GET /projects` — Registry of all indexed workspaces on your machine.
• `POST /generate` — Generate a task-scoped, token-budgeted, and secret-redacted context pack (quick mode ~300 tokens or task mode with query search). Supports dynamic model context budgeting.
• `POST /refresh` — Force incremental rebuild and return fresh pack.
• `POST /capture` — Reserved for bidirectional context capture (returns 501).

v2.6.0 Enhancements

• Warm In-Memory Graph Reuse — Caches parsed symbol and AST dependency graphs across repeat IPC calls with TTL and mtime invalidation for 3x faster response times.
• Model-Aware Dynamic Budgeting — Tunes context pack token density against target context windows (Claude 3.5 Sonnet, GPT-4o, o1, Gemini 1.5 Pro).
• Detached Daemon Lifecycle — tokencap serve --daemon manages background processes with PID tracking (.tokencap/serve.pid) and clean SIGTERM teardown via --stop.

Security & Privacy Guarantees

• Strict Loopback Binding — Listens strictly on 127.0.0.1 (never 0.0.0.0 or public interfaces).
• Pairing Authentication — Every request requires valid X-TokenCap-Token matching the token minted at startup.
• Origin Allowlisting — Browser extension and supported AI chat domains only; unlisted web origins are blocked (403).
• Zero Outbound Calls — Pure local IPC; TokenCap never initiates external network requests.

TokenCap v2.8.0 connects local repository intelligence to ChatGPT, Claude, and Gemini through the TokenCap Companion. The bridge stays on your machine and communicates over authenticated loopback only.

# Build the repository once
tokencap make

# Start the local bridge and open its pairing page
tokencap serve

# Start in the background or inspect the running bridge
tokencap serve --daemon
tokencap serve --status

Companion Flow

1. Start tokencap serve and pair the Companion using the generated local URL.

2. Select an indexed repository and optionally describe the task.

3. Inject a redacted, bounded context pack into a supported browser chat.

4. Capture useful session results; captures are staged and require explicit approval before entering durable memory.

Transfer Guarantees

• Draft-safe — Injection preserves existing composer text, marks its own block, and refuses duplicate insertion.
• Bounded — The requested context budget covers the complete response, including the project primer.
• In-memory — Companion generation does not create a .tokencap/context file per request.
• Local-first — The bridge binds to 127.0.0.1, uses pairing authentication, and makes no outbound calls.
• Recoverable — A generated pack can be previewed, copied, or downloaded when a browser composer changes.

TokenCap v2.9.0 makes TokenCap discoverable and executable by any AI agent through the open skill system. A standard skill definition ships inside the npm tarball under skills/tokencap/ for OpenCode, Claude Code, Cursor, Codex, and Antigravity.

# Install the CLI where the agent works
npm install -g tokencap

# Or install the standalone Skill into your host's skills directory
git clone https://github.com/vansharora21/Tokencap-skill.git <your-host-skills-directory>/tokencap

# Build repository intelligence once
tokencap make

Skill Contents

• `SKILL.md` — Agent instructions and operating boundaries.
• `reference/commands.md` — The current seven-command CLI surface.
• `reference/workflows.md` — Step-by-step playbooks agents can follow.

Hosts choose their own discovery locations. TokenCap never overwrites host configuration automatically.

Workflow Playbooks

• Codebase Onboarding — Build once, start at .tokencap/agent/START_HERE.md, and read only the files returned for the task.
• Change Review — tokencap analyze review, risk findings, symbol impact, and test gaps before sign-off.
• Refactoring — Check blast radius and test coverage before applying a minimal source change.
• Debugging, Architecture Review, Session Handoff & CI — Bounded sequences for the remaining common engineering tasks.

MCP Contract v2

• Stable Tool Contract — Tool names, required inputs, and response behaviour are fixed for the v2 line. Minor releases may add optional fields but never rename a tool or remove an accepted field.
• Generated Artifact Schemas — Artifacts under .tokencap/ are described by published schemas.
• Runtime Artifact Validation — Artifacts are validated at runtime, and failures are returned as structured MCP errors.
• Contract Version Reporting — tokencap_mcp_status returns the active contractVersion.

TokenCap v3.0.0 lets other tools, teammates, and plugins build on the intelligence TokenCap generates. Everything still runs locally: no source upload, no API key, no telemetry.

# Upgrade a v2 workspace once, then rebuild
npm install -g tokencap@3.0.0
tokencap make --migrate
tokencap make

Read-Only SDK

@tokencap/sdk is a dependency-free, dual-module (CommonJS and ES module) interface for intelligence that tokencap make has already generated. It never triggers a build, a watcher, a network request, or a file write. The source lives in packages/sdk of the TokenCap repository.

const { loadIntelligence, search, getImpact, buildContext } = require("@tokencap/sdk");

const intelligence = await loadIntelligence("/path/to/repository");
const files = search(intelligence, "authentication session", { limit: 8 });
const impact = getImpact(intelligence, "src/auth.js", { depth: 2 });
const context = buildContext(intelligence, { task: "Trace session validation", budget: 4000 });

• Required artifacts — .tokencap/brain/knowledge.json and .tokencap/graph/graph-data.json. A missing build reports TOKENCAP_INTELLIGENCE_MISSING; malformed output reports TOKENCAP_ARTIFACT_INVALID.
• Static evidence — Graph and impact answers describe source structure, not runtime behaviour or test coverage.

Team Intelligence

Shared rules, decisions, approvals, profiles, and ADRs are stored as append-only files under .tokencap/team/ and committed with Git. There is no server or cloud account, and TokenCap never commits on your behalf.

tokencap analyze team init --name "Platform"
tokencap analyze team rule --author "Ava" --text "Changes to auth require review."
tokencap analyze team approve-rule --id <rule-id> --author "Ben"
tokencap analyze team decision --author "Ava" --text "Use local Git records."
tokencap analyze team sync-adrs
tokencap analyze team status --json
git add .tokencap/team .gitignore

An approval moves a rule or decision from proposed to accepted. TokenCap records the evidence; it never blocks a commit or settles a disagreement automatically.

Plugin Runtime

Projects opt into local plugins from their own package.json. Each entry must be a workspace-relative JavaScript file; package names and remote modules are refused.

{ "tokencapPlugins": ["./tools/tokencap-plugin.js"] }

• Hooks and tools — Plugins can provide afterBuild and beforeRedact hooks and named tools.
• Confined — Plugins have no require, process, or network access, and can only read and write .tokencap/plugins/<plugin-name>/. Install plugins you trust.

tokencap analyze plugins list
tokencap analyze plugins run <tool-name> --text "input"

Removed v2 Aliases

The seven commands stay the same. Standalone v2 aliases now print their replacement instead of running:

MCP hosts configured before v3 keep working: tokencap mcp remains a hidden alias for tokencap serve --mcp, which new host configs use.

TokenCap v2.7.0 closes the conversation → repository loop by turning completed AI coding sessions into structured, redacted, reviewable handoffs:

# Capture session summary to staged memory
tokencap serve session save --summary "added jwt auth" --files src/auth.ts --decision "use RS256"

# Review staged inbound captures
tokencap serve session save --list
tokencap serve session save --approve <session-id>
tokencap serve session save --reject <session-id>
tokencap serve session save --note <session-id> --text "verified"

# Export latest approved session as Markdown handoff
tokencap serve session handoff

# Build health diagnostics & scoring (0-100)
tokencap analyze health
tokencap make --rebuild

# Evidence-rich risk findings
tokencap analyze risk
tokencap analyze risk --ack <id>

Session Capture v1

• Graph-Grounded Quality Scoring — Captures are validated, bounded, redacted, and scored against the repository graph for path validity, groundedness, specificity, and novelty into confidence tiers.
• Staged, Never Silent — Captures land in .tokencap/memory/inbound/ with provenance; nothing alters durable memory without human approval.
• Approved Sessions Archive — Approved sessions move to .tokencap/memory/sessions/, feeding tokencap serve session handoff, .tokencap/memory/current.md, and MCP latestSession.
• Honest Host Registry — 7 supported hosts (tokencap serve session save --hosts); no host is claimed as auto-capture without verified session-end hooks.

Build Health & Risk Engine

• 0–100 Explainable Score — Evaluates intelligence freshness, source drift, detection completeness, and coverage with direct remediation commands.
• Evidence-Rich Risk — Normalized findings (oversized-file, todo-density, possible-secret) with persistent --ack and --dismiss state. Supports PEP 621 and Poetry pyproject.toml parsing.
• Session ROI — Aggregates observed token savings and dollar ROI across hosts in tokencap serve session list and MCP status.

TokenCap v3 has seven commands: make, ask, analyze, serve, update, help, and version. Every capability is a flag or subcommand of one of them. Commands removed in v3 print their replacement instead of running.

---

Installation

npm install -g tokencap
tokencap --version

---

tokencap make

Build or refresh project intelligence.

tokencap make
tokencap make --watch          # Rebuild on save
tokencap make --rebuild        # Full clean rebuild + health report
tokencap make --migrate        # Upgrade a v2 workspace to the v3 artifact contract
tokencap make --open-graph     # Build and open the interactive graph viewer
tokencap make --package <name> # Build one workspace package

Options

• --profile <name> — compact | balanced | deep | gpt-4o | claude-3-5-sonnet | gemini-1.5-flash | gemini-1.5-pro | llama-3-8b
• --no-pointers — Skip multi-host agent pointer file generation
• --max-files <n> — Maximum number of files to include
• --max-bytes <n> — Total source byte budget

---

tokencap ask

Query your codebase.

tokencap ask "Where is authentication handled?"   # Task-scoped context pack
tokencap ask brain <topic>                         # Project Brain cluster query
tokencap ask impact src/auth/token.js:validateToken # Callers and blast radius
tokencap ask impact --dead-code                    # Uncalled symbols
tokencap ask impact --clusters                     # Functional communities

---

tokencap analyze

Audit, inspect, and report.

tokencap analyze diff --staged
tokencap analyze review --base main
tokencap analyze tests --gaps
tokencap analyze health
tokencap analyze risk --ack <id>
tokencap analyze refactor rename src/auth/token.js:validateToken checkToken --write
tokencap analyze debug --start -- npm test
tokencap analyze security scan
tokencap analyze team status
tokencap analyze plugins list

Subcommands: diff, review, ownership, team, plugins, compress, tests, taint, schema, components, constitution, agent, simplify, stats, debt, health, risk, security, debug, refactor, feedback, verify.

---

tokencap serve

Local services: the browser Companion bridge, the MCP server, and session memory.

tokencap serve                       # Companion bridge on 127.0.0.1:4545
tokencap serve --daemon              # Run the bridge in the background
tokencap serve --stop                # Stop the background bridge
tokencap serve --mcp                 # MCP server over stdio
tokencap serve --mcp --init --client claude-code  # Configure an MCP host
tokencap serve session save --summary "feature completed" --files src/app.js
tokencap serve session list
tokencap serve session handoff

---

tokencap update

Check for updates and upgrade TokenCap.

tokencap update
tokencap update --check

---

tokencap help / version

tokencap help
tokencap version

The TokenCap VS Code extension brings all functionality directly into your editor.

Installation: Search for TokenCap by VanshArora21 in the VS Code Extensions panel, or install the VSIX package manually.

Auto Capture: After installing, TokenCap starts watching your workspace immediately. Every time you save a file, it waits 30 seconds (configurable) then regenerates all three snapshot files.

Status Bar: A $(files) TokenCap • HH:MM item appears in the status bar showing your last snapshot time. Click it to open the command menu.

Command Menu (Quick-Pick):

• Make Snapshot Now
• Open TokenCap Snapshot
• Toggle Auto Capture ON/OFF
• Create Config File

VS Code Settings: