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 provides a simplified 11-command CLI for generating AI-ready project context, retrieving semantic files from questions, analyzing code changes, debugging, packing token-budgeted prompt files, generating AI Agent Skill Packs, querying cluster intelligence, and serving local MCP requests.

---

Installation

Install TokenCap globally:

npm install -g tokencap

Verify installation:

tokencap --version

---

tokencap mcp

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

tokencap mcp --init

Options

• --init — Auto-detect host IDE and write workspace configuration.
• --client <host> — Specify client host explicitly (vscode | antigravity | codex | cursor | claude | windsurf | cline).
• --tools — List all 11 MCP tool endpoints and descriptions.
• --test — Run self-test suite calling all endpoints.
• --health — Run one-shot server health check.

---

tokencap brain

Project Brain — unified intelligence query about any part of your codebase.

tokencap brain <topic>

Options

• --impact — Show affected file/feature count, critical files, and risk level.
• --architecture — Render dependency chain ASCII view for the cluster.
• --review — Show review group files and reason for grouping.
• --timeline — Show git commit history (date + message) for cluster files.
• --risk — Show risk areas and affected files.
• --deps — Show full depends-on and used-by lists.

---

tokencap agent

Generate the Self-Loading Universal Context Layer.

tokencap agent

Options

• --full — Run the full pipeline (default)
• --architecture — Focused generation of architecture details
• --rules — Focused generation of project coding rules and conventions
• --skills — Focused generation of agent skill definitions and instructions
• --no-agents-file — Skip generating the root-level AGENTS.md file
• --export <target> — Export rules directly to Cursor, Windsurf, Cline, or Roo Code formats.
• --execution — Generate the Execution Contract (v1.1.0) under .tokencap/agent/execution-contract/
• --strict — Strict mode: enables scope drift confirmation and gating rules (v1.1.0)

---

tokencap constitution

Repository Constitution management.

tokencap constitution

Options

• --json — Output raw JSON rule list and graph data.
• --diff — Diff current constitution rules against the last run.
• --history — Show snapshot history and score tracking over time.
• --impact <file> — Query which constitution laws are affected by a specific file.

Subcommands

• search <query> — Search constitution rules by keyword, ID, severity, or category.

---

tokencap ask

Smart context retrieval from a natural language question.

tokencap ask "How does authentication work?"

Options

• --mode <name> — review | debug | architecture (override auto-detected mode)
• --budget <number> — Custom token budget. Default: 12000
• --json — Also export context.json
• --no-prompt — Skip generating the prompt.md file

---

tokencap context

Manual context generation by topic keyword.

tokencap context auth

Options

• --mode <name> — Override mode: review | debug | architecture
• --budget <number> — Custom token budget. Default: 8000
• --json — Also export context.json
• --prompt — Generate prompt.md file

---

tokencap make

Generate a complete AI-ready project context snapshot.

tokencap make

What it does

Scans your repository and generates the main snapshot files:

• TOKENCAP.md — main workspace snapshot containing file content, Git context, diffs, TODOs, and redacted secrets
• TOKENCAP_GRAPH.md — project knowledge graph
• TOKENCAP_MEMORY.md — developer context memory

Options

• --profile <name> — compact | balanced | deep | gpt-4o | claude-3-5-sonnet | gemini-1.5-flash | gemini-1.5-pro | llama-3-8b
• --max-files <n> — Maximum number of files to include
• --max-bytes <n> — Total source byte budget
• --max-file-bytes <n> — Per-file content byte limit
• --max-diff-bytes <n> — Git diff byte budget
• --no-diff — Skip Git diff snippets
• --no-contents — Skip selected file contents (structure outline only)

---

tokencap graph

Analyze the code knowledge graph and dependency topology.

tokencap graph

Presets & Options

• --open — Opens the Obsidian-style three-panel interactive viewer in default browser
• --full — Runs full intelligence (JSON export + AI narrative summary + graph diff + viewer)
• --minimal — Generates only JSON exports (graph-data.json, nodes.json, edges.json)
• --quiet — Suppresses verbose logs and shows only a clean stats block
• --diff — Generates graph-diff.md comparing current relationships vs last run
• --ai — Generates AI narrative summary only
• --json — Exports raw JSON files to .tokencap/graph/

---

tokencap diff

Perform a semantic Change Intelligence analysis on your edits.

tokencap diff

Options

• --staged — Analyze only staged changes (prior to a commit)
• --last — Analyze changes in the last commit (HEAD~1..HEAD)
• --pr — Generate a pull request summary description
• --prompt — Generate an optimized AI code review prompt
• --json — Output machine-readable JSON analysis

---

tokencap debug

Unified debug session management.

tokencap debug --start

Debug Flags

• --start — Start a new debug session (append '-- <command>' to run command and auto-capture stderr, failed tests, and traces)
• --end — End the active debug session, compile final handoff report, and archive it
• --log "message" — Add a timestamped update or discovery note to the active session timeline

Example Workflow

tokencap debug --start -- npm test
# (investigate and edit files based on active debug notes)
tokencap debug --log "Reverted middleware changes - test still failing"
tokencap debug --end
# (paste .tokencap/debug/active.md into your AI assistant)

---

tokencap pack

Generate a token-budgeted, importance-scored context pack for LLM prompts.

tokencap pack <topic>

Options

• <topic> — Optional topic or cluster keyword (queries Brain to scope context pack)
• --mode <name> — Select compression mode: review | debug | architecture | minimal
• --budget <number> — Set maximum token budget. Default: 20000

---

tokencap watch

Automatically regenerate TokenCap snapshots on file saves.

tokencap watch

Options

• --debounce <ms> — Milliseconds to wait after a file change before regenerating. Default: 30000

---

Recommended Workflow

Self-Maintaining MCP Service (v1.5)

tokencap mcp --init

---

Understand any part of your codebase instantly (v0.9)

tokencap brain auth

---

Teach an AI Agent (v0.8)

tokencap agent

---

Teach an AI Agent Engineering Discipline (v1.1)

tokencap agent --execution

---

Teach an AI Agent Permanent Engineering Laws (v1.2)

tokencap constitution

---

Ask about any part of your codebase (v0.7)

tokencap ask "How does authentication work?"

---

Quick topic context (v0.7)

tokencap context payments

---

Daily Development

tokencap watch

---

Before Asking AI

tokencap make

---

During Debugging

tokencap debug --start -- npm test

tokencap debug --log "Tested middleware"

tokencap debug --end

---

Before Deployment

tokencap diff

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: