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 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 refactor rename src/auth/token.js:validateToken checkToken
tokencap refactor rm-dead src/util/helpers.js:unusedHelper

# Apply refactoring changes atomically
tokencap 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 feedback record --agent claude --outcome helped --task "refactor auth"
tokencap 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 impact src/server/handler.go:ServeHTTP\ntokencap 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.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 remember --summary "added jwt auth" --files src/auth.ts --decision "use RS256"

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

# Export latest approved session as Markdown handoff
tokencap handoff

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

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

# Watcher controls
tokencap watch-config --debounce 15000 --ignore "dist/*"

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 handoff, .tokencap/memory/current.md, and MCP latestSession.
• Honest Host Registry — 7 supported hosts (tokencap remember --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 memory and MCP status.

TokenCap provides a CLI for generating AI-ready project context, querying intelligence, safe refactoring, static test analysis, analyzing changes, debugging, secret scanning, and serving local MCP requests.

---

Installation

Install TokenCap globally:

npm install -g tokencap

Verify installation:

tokencap --version

---

tokencap remember

Capture, stage, and review AI session summaries.

tokencap remember --summary "feature completed" --files src/app.js
tokencap remember --list
tokencap remember --approve <id>
tokencap remember --reject <id>

---

tokencap handoff

Export the latest approved session handoff as Markdown.

tokencap handoff

---

tokencap health

Calculate repository intelligence build health (0-100 score).

tokencap health
tokencap rebuild

---

tokencap risk

Review evidence-rich risk findings and acknowledge/dismiss items.

tokencap risk
tokencap risk --ack <id>
tokencap risk --dismiss <id>

---

tokencap watch-config

Configure persistent file watching parameters.

tokencap watch-config --debounce 10000 --ignore "dist/*"

---

tokencap serve

Start the local loopback HTTP bridge for browser companions.

tokencap serve
tokencap serve --daemon       # Run in background
tokencap serve --stop         # Stop running daemon
tokencap serve --port 4545    # Custom port

---

tokencap refactor

Plan and apply safe symbol renames or dead code removal across the AST call graph.

tokencap refactor rename src/auth/token.js:validateToken checkToken
tokencap refactor rename src/auth/token.js:validateToken checkToken --write
tokencap refactor rm-dead src/util/helpers.js:unusedHelper --write

---

tokencap analyze

Run codebase analysis, static test mapping, review packets, ownership signals, or dead code detection.

tokencap analyze tests --gaps
tokencap analyze tests --coverage coverage/lcov.info
tokencap analyze review --base main
tokencap analyze ownership --history
tokencap analyze simplify

---

tokencap feedback

Record and report local context utility for AI coding sessions.

tokencap feedback record --agent claude --outcome helped
tokencap feedback report

---

tokencap make

Generate a complete AI-ready project context snapshot.

tokencap make

Options

• --profile <name> — compact | balanced | deep | gpt-4o | claude-3-5-sonnet | gemini-1.5-flash | gemini-1.5-pro | llama-3-8b
• --full — Force full rebuild (bypasses incremental cache)
• --no-pointers — Skip multi-host agent pointer file generation
• --open-graph — Open interactive Obsidian-style graph viewer in default browser
• --max-files <n> — Maximum number of files to include
• --max-bytes <n> — Total source byte budget

---

tokencap scan

Scan workspace source files for leaked secrets and high-entropy API tokens.

tokencap scan

---

tokencap audit

Perform a security audit on generated TokenCap outputs to verify redaction engine compliance.

tokencap audit

---

tokencap upgrade

Check for and install updates to TokenCap.

tokencap upgrade

---

tokencap mcp

Model Context Protocol (MCP) server & host IDE configuration.

tokencap mcp --init --client claude

---

tokencap brain

Project Brain — unified cluster intelligence query.

tokencap brain <topic>

---

tokencap agent

Generate the Self-Loading Universal Context Layer.

tokencap agent --execution

---

tokencap constitution

Repository Constitution rules and laws management.

tokencap constitution

---

tokencap diff

Perform semantic Change Intelligence analysis.

tokencap diff --staged

---

tokencap debug

Unified debug session management.

tokencap debug --start -- npm test

---

tokencap pack

Generate token-budgeted, importance-scored context packs.

tokencap pack <topic>

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: