CLI Reference

Master the TokenCap command-line interface. A powerful, local-first utility designed to package codebase context for AI tools.

download

Install globally

Get started by installing the TokenCap CLI globally via npm. This provides the tokencap executable.

bash

$npm install -g tokencap

Flagship Command (v0.9)

Project Brain (brain)

Ask about any part of your codebase and get a unified intelligence view: files, risk, architecture, dependencies, review group, recent changes, and git timeline — all from a single command.

check_circle6 Brain Modes: Impact, Architecture, Review, Timeline, Risk, and Deps

check_circleFuzzy matching: Automatically matches topics even with partial input

Terminal — tokencap brain

>tokencap brain auth

Risk: CRITICAL (🔴)

✔ Fuzzy matched cluster: Authentication

✔ Resolved 6 files in cluster

June 3 | Session Validation Added (authService.ts)

Central File: authService.ts (8 importers)
Review Group: Auth + Schema

Flagship Command

Agent intelligence (agent)

Analyze your repository and automatically generate a complete Self-Loading Universal Context Layer (AGENTS.md, START_HERE.md) or Execution Contract (v1.1.0) under .tokencap/agent/ to teach AI agents engineering discipline.

check_circleUniversal Onboarding: Generates root AGENTS.md, START_HERE.md, context-manifest.json

check_circleExecution Contract (v1.1): 8 lifecycle files covering Scope Drift, Confidence Rating, and Recovery Mode

Terminal — tokencap agent

>tokencap agent --execution

✔ Initializing Execution Contract pipeline...

✔ Compiling current state & engineering rules...

✔ Activating Scope Drift Detection logic...

✔ Generating 8 contract files...

Generated: .tokencap/agent/execution-contract/
Includes: execution-state.md, execution-scope.md

Smart context retrieval (ask)

Ask a natural language question and TokenCap automatically retrieves only the relevant files.

Terminal — tokencap ask

>tokencap ask "How does authentication work?"

✔ Analyzing question keywords...

✔ Matching clusters: Authentication (95%)

✔ Performing 2-hop BFS import search...

Generated: .tokencap/context/auth-context.md
Generated: .tokencap/context/auth-prompt.md

Topic context (context)

Manually compile prompt-optimized context files for a specific keyword or topic.

Terminal — tokencap context

>tokencap context payments --budget 8000

✔ Compiling payments context...

[14:04:12] Token Budget Allocated: 8,000 tokens

Generated: .tokencap/context/payments-context.md

Generate snapshot (make)

Generate all three files: main snapshot, project knowledge graph, and developer context memory in one command.

Terminal — tokencap make

>tokencap make --profile balanced

✔ Scanning files...

✔ Generating TOKENCAP_GRAPH.md...

✔ Generating TOKENCAP_MEMORY.md...

Generated: TOKENCAP.md
Generated: TOKENCAP_GRAPH.md
Generated: TOKENCAP_MEMORY.md

Watch mode

Start a background watcher that regenerates all snapshot files automatically whenever a file changes.

Terminal — tokencap watch

>tokencap watch --debounce 3000

[14:02:21] Watching workspace for changes...

● Change detected in src/app/login/page.tsx

[14:02:45] Debouncing and regenerating snapshot files...

Context packing (pack)

Pack your project workspace into a token-budgeted, importance-scored context pack for LLMs.

Terminal — tokencap pack

>tokencap pack --mode review --budget 20000

✔ Analyzing file graph centrality...

✔ Applying representation tiers...

Generated: .tokencap/packs/review.md (18,450 tokens)
Tiers: 12 full, 8 outlined, 5 AST, 14 reference-only

Change intelligence (diff)

Perform semantic change analysis to determine risk rating, breaking changes, and suggested tests.

Terminal — tokencap diff

>tokencap diff --staged

[14:03:01] Analyzing 5 staged files...

Risk Rating: MEDIUM

- Modified API: /api/auth/login
- Suggested Tests: Session expiry, redirect validation

Repository constitution (constitution)

Inspect permanent codebase laws, view compliance ratings, verify schema rules, or search for rules by severity or category.

Terminal — tokencap constitution

>tokencap constitution

✔ Loading ConstitutionGraph...

Constitution Score: 92 / 100

Top Rules (Never Violate):

- 🔒 CONST-SEC-001 — Password hashing algorithm must not be changed.

- 🔴 CONST-COMP-001 — PCI-DSS compliance required for payment routes.

Configuration

.tokencap.json

Initialize a local project configuration or print the currently resolved configuration including profile defaults.

INITIALIZE CONFIG

tokencap init

Creates a default config file .tokencap.json in your workspace root.

RESOLVE CONFIG

tokencap config

Prints resolved configuration tree combined with CLI overrides.

// Resolved Config Output

{
  "profile": "balanced",
  "outputPath": "TOKENCAP.md",
  "maxFiles": 90,
  "maxSourceBytes": 220000,
  "includeGitDiff": true,
  "redactSecrets": true
}

CLI Options

Flag	Description	Default
--profile <name>	Select context profile (compact, balanced, deep, gpt-4o, etc.).	balanced
--root <path>	Specify the workspace root directory.	.
--out <path>	Snapshot output path (for main snapshot).	TOKENCAP.md
--max-files <n>	Maximum number of files to include in snapshot.	90
--max-bytes <n>	Total source byte budget for files combined.	220000
--max-file-bytes <n>	Per-file content byte limit.	14000
--no-diff	Skip including Git diff snippets in the snapshot.	false
--no-contents	Skip selected source file contents (outline only).	false
--debounce <ms>	Regeneration debounce delay in watch mode.	3000
--mode <name>	Retrieval/pack mode: review \| debug \| architecture \| minimal.	review
--budget <number>	Custom token budget for ask/context/pack commands.	12000 / 8000 / 20000
--staged	Analyze only staged changes (for diff command).	false
--last	Analyze changes in the last commit (for diff command).	false
--pr	Generate PR summary description (for diff command).	false
--prompt	Generate AI prompt/review prompt (for ask/context/diff commands).	true (ask)
--no-prompt	Skip prompt.md generation (for ask command).	false
--json	Output machine-readable JSON (for ask/context/diff/graph/agent/constitution commands).	false
--open	Open interactive HTML graph viewer in browser (for graph command).	false
--ai	Generate detailed narrative AI summary (for graph command).	false
--diff	Generate graph structural diff vs last run (for graph command) or constitution diff (for constitution command).	false
--full	Run full 8-phase pipeline (for agent command).	true
--export <target>	Export rules directly to Cursor, Windsurf, Cline, or Roo Code formats (for agent command).	false
--execution	Generate the Execution Contract lifecycle suite under .tokencap/agent/execution-contract/ (for agent command).	false
--strict	Strict mode: enables scope drift confirmation and gating rules (for agent command).	false
--history	Show snapshot history and score tracking over time (for constitution command).	false
--impact <file>	Query which constitution laws are affected by a file (for constitution command) or show affected file/feature count and risk summary (for brain command).	N/A
--architecture	Render dependency chain ASCII view (brain) or architecture mapping (agent).	false
--rules	Focused generation of coding rules (for agent command).	false
--skills	Focused generation of agent skill definitions (for agent command).	false
--review	Show review group files and grouping reasons (for brain command).	false
--timeline	Show git commit history for cluster files (for brain command).	false
--risk	Show risk areas and affected files (for brain command).	false
--deps	Show depends-on and used-by lists (for brain command).	false

Built for speed.

Highly optimized JS parser engine ensures execution times in milliseconds.

CLI Options

Flag	Description	Default
--profile <name>	Select context profile (compact, balanced, deep, gpt-4o, etc.).	balanced
--root <path>	Specify the workspace root directory.	.
--out <path>	Snapshot output path (for main snapshot).	TOKENCAP.md
--max-files <n>	Maximum number of files to include in snapshot.	90
--max-bytes <n>	Total source byte budget for files combined.	220000
--max-file-bytes <n>	Per-file content byte limit.	14000
--no-diff	Skip including Git diff snippets in the snapshot.	false
--no-contents	Skip selected source file contents (outline only).	false
--debounce <ms>	Regeneration debounce delay in watch mode.	3000
--mode <name>	Retrieval/pack mode: review \| debug \| architecture \| minimal.	review
--budget <number>	Custom token budget for ask/context/pack commands.	12000 / 8000 / 20000
--staged	Analyze only staged changes (for diff command).	false
--last	Analyze changes in the last commit (for diff command).	false
--pr	Generate PR summary description (for diff command).	false
--prompt	Generate AI prompt/review prompt (for ask/context/diff commands).	true (ask)
--no-prompt	Skip prompt.md generation (for ask command).	false
--json	Output machine-readable JSON (for ask/context/diff/graph/agent/constitution commands).	false
--open	Open interactive HTML graph viewer in browser (for graph command).	false
--ai	Generate detailed narrative AI summary (for graph command).	false
--diff	Generate graph structural diff vs last run (for graph command) or constitution diff (for constitution command).	false
--full	Run full 8-phase pipeline (for agent command).	true
--export <target>	Export rules directly to Cursor, Windsurf, Cline, or Roo Code formats (for agent command).	false
--execution	Generate the Execution Contract lifecycle suite under .tokencap/agent/execution-contract/ (for agent command).	false
--strict	Strict mode: enables scope drift confirmation and gating rules (for agent command).	false
--history	Show snapshot history and score tracking over time (for constitution command).	false
--impact <file>	Query which constitution laws are affected by a file (for constitution command) or show affected file/feature count and risk summary (for brain command).	N/A
--architecture	Render dependency chain ASCII view (brain) or architecture mapping (agent).	false
--rules	Focused generation of coding rules (for agent command).	false
--skills	Focused generation of agent skill definitions (for agent command).	false
--review	Show review group files and grouping reasons (for brain command).	false
--timeline	Show git commit history for cluster files (for brain command).	false
--risk	Show risk areas and affected files (for brain command).	false
--deps	Show depends-on and used-by lists (for brain command).	false