TokenCap

Repository Intelligence tells AI what exists. Execution Contract tells AI how work should proceed. Repository Constitution tells AI what must never change. Incremental Intelligence Engine ensures it never rebuilds what hasn't changed.

TokenCap is a Self-Loading Universal Context Layer + Execution Contract + Repository Constitution + Incremental Intelligence Engine + Repository Intelligence Service for AI Coding Agents.

It analyzes your repository once and generates a persistent knowledge layer that any AI can query — live, during reasoning, on demand.

No cloud. No accounts. No API keys. Just a local intelligence service.

Current release anchor: v1.5.0.

The Problem

Every new AI session starts from zero.

New Model
↓
Scans repository
↓
Infers architecture
↓
Discovers dependencies
↓
Learns conventions
↓
Finally starts working

This happens every time you switch models, IDEs, or sessions.

Wasted tokens. Wasted time. Repeated discovery.

But understanding the repository is only half the problem.

Even after an AI understands your project, two more problems remain:

Execution failures:

Entering reasoning loops
Rewriting large sections unnecessarily
Modifying unrelated files
Expanding scope without reason
Concluding "Fixed." without verification

Rebuild waste:

Repository changes one file → entire knowledge base is rebuilt
Watch mode regenerates everything on every save
CI pipelines pay full cost for minor edits

The Solution

Repository
        │
        ▼
tokencap make          ← Incremental Build (only rebuilds what changed)
        │
        ▼
Project Brain
        │
        ▼
tokencap agent         ← Transfer Knowledge
        │
        ▼
Self-Loading Universal Context Layer
        │
        ▼
tokencap agent --execution  ← Engineering Discipline
        │
        ▼
Execution Contract
        │
        ▼
tokencap constitution  ← Permanent Engineering Laws
        │
        ▼
Repository Constitution
        │
        ▼
AI Coding Agent        ← Starts working immediately, with discipline and boundaries

Build project knowledge once. Define engineering discipline once. Encode permanent laws once. AI queries it on demand — only what it needs, exactly when it needs it.

Quick Start

npm install -g tokencap        # 1. Install
tokencap mcp --init            # 2. Wire your IDE

Open your IDE. TokenCap initializes intelligence and keeps it current while the MCP server is running.

What's New in v1.5.0 - Self-Maintaining MCP Intelligence

Version 1.5.0 removes the manual preparation work around MCP. Connect the host once, and TokenCap maintains the repository intelligence it needs.

Automatic initialization: MCP startup runs tokencap make before tools become available. Users no longer need to run an initial build manually.
Live repository memory: the MCP process starts an internal watcher for source and .tokencap-notes.md changes, keeping generated intelligence and session memory current while the host is running.
Universal host setup: tokencap mcp --init supports Claude Code, Cursor, Windsurf, Cline, VS Code, Antigravity, and Codex. Use --client <host> when a workspace contains more than one supported host.
Safer configuration: initialization merges the TokenCap server into an existing valid host configuration instead of replacing unrelated servers.
Faster builds: full builds resolve and enrich the graph once, then share that context between the agent and brain builders.
Durable MCP metadata: knowledge.json now stores the detected tech stack, removing the MCP overview dependency on generated markdown.

For MCP setup, workflows, latency interpretation, and diagnostics, see the MCP guide.

What's New in v1.4.0 — Repository Intelligence Service

Don't read repository intelligence. Query it.

Before v1.4.0, every AI session started with a cold load:

Session Start
↓
Load agent-pack.md (20,000 tokens)
↓
Load execution contract (8 files)
↓
Load constitution rules
↓
Start working — context already stale

v1.4.0 replaces that with a live local intelligence service:

Session Start
↓
tokencap_overview          (300 tokens)
↓
"Fix login redirect"
↓
tokencap_files({ query: "login redirect" })         (700 tokens)
tokencap_dependencies({ target: "src/auth/login.js" }) (400 tokens)
tokencap_constitution({ scope: "authentication" })  (300 tokens)
tokencap_verify({ cluster: "authentication" })      (200 tokens)
↓
Done — 1,900 tokens total   (vs 20,000 before)

11 MCP Endpoints

Endpoint	What it returns
`tokencap_overview`	Tech stack, cluster list, risk summary, last build time
`tokencap_cluster`	Full intelligence for one cluster: files, deps, risk, changes
`tokencap_files`	Most relevant files for a task, ranked by graph + recency + risk
`tokencap_dependencies`	Upstream providers + downstream consumers up to N hops
`tokencap_constitution`	Constitution rules scoped to a cluster, file, or rule ID
`tokencap_impact`	Blast radius of a proposed change: affected clusters + broken rules
`tokencap_execution`	Execution-contract guidance for the current engineering phase
`tokencap_delta`	What changed since last build — clusters, files, rules
`tokencap_search`	Cross-layer search across brain, graph, constitution, and files
`tokencap_verify`	Test commands, test files, lint rules, review checklist
`tokencap_mcp_status`	Server uptime, cache hit rate, per-endpoint call counts

Setup — two steps

1. Wire your IDE (one time):

tokencap mcp --init

Detects Claude Code, Cursor, Windsurf, Cline, VS Code, Antigravity, or Codex and writes workspace configuration automatically. Use --client <host> when more than one host is present.

2. Start the server:

tokencap mcp

Stdio MCP server. On startup it runs tokencap make, then keeps an internal watcher active for source and .tokencap-notes.md changes. Your IDE manages the process. A local server-log sample measured 0-2 ms of handler time; host-visible latency also includes MCP transport and host overhead.

See the MCP guide for host-specific setup, recommended tool workflows, diagnostics, and the difference between server processing time and end-to-end MCP latency.

All CLI flags

tokencap mcp                # Start MCP server (stdio)
tokencap mcp --tools        # List all 11 endpoints and descriptions
tokencap mcp --test         # Self-test: call every endpoint, verify output
tokencap mcp --health       # One-shot health check (no server started)
tokencap mcp --init         # Write IDE config to correct location automatically
tokencap mcp --init --client vscode       # Write .vscode/mcp.json
tokencap mcp --init --client antigravity  # Write .agents/mcp_config.json
tokencap mcp --init --client codex        # Write .codex/config.toml

Token savings

Scenario	File-based	v1.5 MCP service	Savings
Simple bug fix	20,000 tokens	1,500	92%
Feature addition	20,000 tokens	4,000	80%
Architecture Q	20,000 tokens	2,500	87%
Code review	20,000 tokens	3,500	82%

IDE compatibility

IDE	How
Claude Code	`tokencap mcp --init` writes `.claude/mcp.json`
Cursor	`tokencap mcp --init` writes `.cursor/mcp.json`
Windsurf	`tokencap mcp --init` writes `.windsurf/mcp.json`
Cline / Roo Code	Copy`.tokencap/mcp/cline.json` to your settings
Claude Desktop	Use`.tokencap/mcp/claude-desktop.json` (works via `npx`, no install needed)
VS Code	`tokencap mcp --init --client vscode` writes `.vscode/mcp.json`
Antigravity	`tokencap mcp --init --client antigravity` writes `.agents/mcp_config.json`
Codex	`tokencap mcp --init --client codex` writes `.codex/config.toml`

What's New in v1.4.0 — Security Hardening Engine

TokenCap may detect secrets. TokenCap must never preserve them.

Every repository file read now passes through a centralized redaction engine before becoming intelligence output. Secrets are caught and replaced with safe markers — no secret value ever survives into .tokencap/ output.

What gets caught

Category	Examples
API Keys	OpenAI (`sk-...`), AWS (`AKIA...`), Google (`AIza...`), Stripe (`sk_live_...`)
Tokens	Slack (`xoxb-...`), npm (`npm_...`), Vercel, Netlify, Cloudflare, Bearer
Secrets	Database URLs, JWT secrets, passwords, session secrets
Private Keys	PEM blocks (RSA, EC, DSA, PKCS#8), SSH keys, service account JSON
High Entropy	Random strings ≥32 chars with Shannon entropy ≥4.5
Sensitive Files	`.env`, `.pem`, `.key`, `id_rsa`, `credentials.json`, `terraform.tfvars`

What's safe (false positive prevention)

Normal code, imports, function calls
package.json dependencies
CSS colors, UUIDs, content hashes
Lockfile integrity hashes, source maps, minified code

Redaction markers

[REDACTED:SECRET]    — passwords, JWT secrets
[REDACTED:KEY]       — API keys
[REDACTED:TOKEN]     — authentication tokens
[REDACTED:URL]       — database URLs, Sentry DSNs
[REDACTED:PEM]       — private keys and certificates
[REDACTED:ENTROPY]   — high-entropy strings
[REDACTED:PATH]      — absolute filesystem paths (opt-in)

New CLI Commands

tokencap scan                    # Scan outputs for leaked secrets
tokencap scan --ci               # CI mode (exit non-zero on leaks)
tokencap scan --report-only      # Report without quarantine
tokencap scan --auto-rebuild     # Quarantine + auto-rebuild

tokencap audit                   # View redaction audit trail
tokencap audit --file <path>     # Filter by file
tokencap audit --json            # JSON output

tokencap upgrade                 # Check for and install updates
tokencap upgrade --check         # Check only, don't install

tokencap version                 # Show installed version

Network policy

Zero network egress by default. Only tokencap upgrade touches the network. No fetch, axios, or http imports exist anywhere in the codebase.

Configuration

Customize security behavior via tokencap.security.yaml:

ignorePatterns:        # Pattern names to skip (false positive whitelist)
  - generic-env
whitelistPatterns:     # Substrings to never redact
  - "test-fixture-"
redactPaths: false     # Enable absolute path redaction
entropyThreshold: 4.5  # Shannon entropy threshold
customRules:           # Additional regex patterns
  - name: internal-id
    regex: "INTERNAL-[A-Z0-9]{12}"
    marker: SECRET

Security architecture

Repository Source Files
        │
        ▼
  ┌─────────────┐
  │  redact()   │ ◄── Central chokepoint — all reads pass through here
  └──────┬──────┘
         │ Content with [REDACTED:*] markers
         ▼
  ┌─────────────┐
  │ Build Engine│ capsule, graph, brain, agent, constitution, pack
  └──────┬──────┘
         │
         ▼
  ┌─────────────┐
  │  .tokencap/ │ Generated output (sanitized)
  └──────┬──────┘
         │
         ▼
  ┌─────────────┐
  │  MCP Server │ Final redact() pass on response envelope
  └─────────────┘

See THREAT_MODEL.md for the full threat model.

What's New in v1.3.0 — Incremental Intelligence Engine

Analyze once. Update only what changed.

Every time tokencap make ran before, it rebuilt the entire repository intelligence — graph, brain, constitution, agent files — from scratch.

Even if a single file changed.

v1.3.0 ends that.

v0.x  Repository Intelligence  — "What exists?"
  ↓
v1.0  Repository Memory        — "How do I stop rediscovering it?"
  ↓
v1.1  Execution Contract       — "How should AI execute work?"
  ↓
v1.2  Repository Constitution  — "What must never change?"
  ↓
v1.3  Incremental Intelligence — "Never rebuild what hasn't changed."
  ↓
v1.4  Intelligence Service     — "Query it. Don't load it."

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)

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)

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.

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/

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.

What's New in v1.2.0 — Repository Constitution

Teach AI what must never change.

Every mature software system contains architectural decisions that should never be violated — regardless of the current task.

Examples of permanent laws:

Public API contracts
Database schema invariants
Authentication contract
Payment state machines
Security boundaries
Compliance requirements (PCI-DSS, GDPR, HIPAA)
Critical business flows
Backward compatibility guarantees

Generate It

tokencap make
# or standalone:
tokencap constitution

What It Generates

.tokencap/constitution/
  constitution.json            ← Graph — single source of truth
  constitution.md              ← Human-readable
  constitution.yaml            ← Structured export
  constitution-graph.html      ← Interactive graph UI
  api-contracts.yaml           ← Public API laws
  schema-invariants.yaml       ← Database schema laws
  architecture-laws.md         ← Architectural boundaries
  security-boundaries.md       ← Security laws
  compliance-rules.md          ← PCI-DSS, GDPR, HIPAA, SOC 2
  critical-flows.md            ← Critical flow protection
  constitution-history/        ← Timestamped snapshots

Constitution Score

Every run generates a health score:

Constitution Score: 92 / 100

Architecture:   100
API Stability:   90
Schema:          90
Security:        85
Compliance:     100

Rule Structure

Every rule gets a stable ID:

CONST-SEC-001    Security boundary rule [#1](https://github.com/vansharora21/TOKENCAP/issues/1)
CONST-API-001    Public API contract [#1](https://github.com/vansharora21/TOKENCAP/issues/1)
CONST-ARCH-001   Architecture law [#1](https://github.com/vansharora21/TOKENCAP/issues/1)
CONST-SCHEMA-001 Schema invariant [#1](https://github.com/vansharora21/TOKENCAP/issues/1)
CONST-COMP-001   Compliance requirement [#1](https://github.com/vansharora21/TOKENCAP/issues/1)
CONST-FLOW-001   Critical flow [#1](https://github.com/vansharora21/TOKENCAP/issues/1)

Field	Purpose
`id`	Stable identifier — never changes
`severity`	`IMMUTABLE` \| `CRITICAL` \| `HIGH` \| `WARNING` \| `INFO`
`confidence`	`0.0–1.0` (1.0 = manual, 0.98 = strong signal, 0.65 = heuristic)
`description`	Plain-language law
`reason`	Why this rule exists
`whatBreaks`	What breaks if violated
`derivedFrom`	Which files this was inferred from
`relationships`	`protects:CONST-API-001`, `blocks:CONST-SCHEMA-003`
`manual`	`true` if loaded from `tokencap.constitution.yaml`

Manual Overrides

# tokencap.constitution.yaml
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."

CLI Commands

tokencap constitution                       # Show all rules, score, top 10 laws
tokencap constitution --json               # Raw JSON output
tokencap constitution --diff               # Changes since last run
tokencap constitution --history            # Snapshot history
tokencap constitution --impact <file>      # Which rules does this file affect?
tokencap constitution search auth          # Search by keyword, ID, severity, category

Version Summary

Version	Name	One-liner	Key Command
v1.5.0	Self-Maintaining MCP Intelligence	MCP auto-builds and watches repositories; setup supports VS Code, Antigravity, and Codex	`tokencap mcp --init`
v1.4.0	Security Hardening + Intelligence Service	Centralized redaction engine,`tokencap scan/audit/upgrade`, zero secret leakage, MCP live queries	`tokencap scan`
v1.3.0	Incremental Intelligence Engine	Only rebuilds what changed — sub-100ms for single-file edits	`tokencap make`
v1.2.0	Repository Constitution	Permanent engineering laws the AI must never violate	`tokencap constitution`
v1.1.0	Execution Contract	8-file engineering discipline system — scope drift detection, recovery mode, confidence rating	`tokencap agent --execution`
v1.0.0	Self-Loading Context Layer	AI auto-discovers`AGENTS.md` → loads project intelligence with zero human intervention	`tokencap agent`
v0.9	Project Brain	Unified knowledge base — query any cluster by name	`tokencap brain <topic>`
v0.7	Smart Context	Token-budgeted context packs scoped to a topic	`tokencap pack <topic>`

Getting Started

npm install -g tokencap

Run from any project root:

# Build intelligence (incremental after first run)
tokencap make

# Transfer knowledge to AI
tokencap agent

# Add execution discipline
tokencap agent --execution

# Query the Brain
tokencap brain auth

# Export scoped context
tokencap pack auth

5 Commands to Remember

tokencap make                       # BUILD      — incremental by default
tokencap brain <topic>              # QUERY      — understand any cluster instantly
tokencap pack <topic>               # EXPORT     — AI-ready scoped context
tokencap agent                      # TRANSFER   — Self-Loading Universal Context Layer
tokencap agent --execution          # DISCIPLINE — Execution Contract

Command	Mental Model	What it does
`tokencap make`	Build Intelligence	Incremental by default. Full graph + brain + constitution on first run, then only updates what changed.
`tokencap brain auth`	Ask Intelligence	Files, risk, architecture, deps, changes for any cluster.
`tokencap pack auth`	Export Intelligence	Token-budgeted context pack scoped to a cluster.
`tokencap agent`	Transfer Knowledge	Generates the Self-Loading Universal Context Layer — 13 files + root AGENTS.md.
`tokencap agent --execution`	Engineering Discipline	Generates the Execution Contract — 8 files in`.tokencap/agent/execution-contract/`.

All Commands

For new v1.5.0 automation, prefer tokencap make --watch to tokencap watch, tokencap make --open-graph to tokencap graph, and tokencap pack to tokencap ask or tokencap context. The older commands remain compatibility aliases and print a deprecation warning.

Command	What it does
`tokencap make`	Incremental build — graph + brain + constitution + agent (only what changed)
`tokencap make --full`	Force full rebuild (v1.2.0 behavior)
`tokencap make --rebuild-brain`	Rebuild only the Brain
`tokencap make --rebuild-constitution`	Rebuild only the Constitution
`tokencap make --rebuild-graph`	Rebuild only the Graph
`tokencap make --clean-cache`	Clear incremental cache (next build = full)
`tokencap make --watch`	Watch and incrementally rebuild after changes
`tokencap make --open-graph`	Build and open graph HTML
`tokencap agent`	Self-Loading Universal Context Layer (v1.0.0 — flagship)
`tokencap agent --execution`	Execution Contract (v1.1.0)
`tokencap constitution`	Repository Constitution (v1.2.0)
`tokencap brain`	Project Brain — unified intelligence query (v0.9)
`tokencap pack`	Context pack — by topic or mode
`tokencap ask`	Smart context retrieval from a question (v0.7)
`tokencap context`	Build focused context for a topic (v0.7)
`tokencap graph`	Code knowledge graph (interactive viewer)
`tokencap diff`	Change intelligence & risk analysis
`tokencap debug`	Debug session management
`tokencap watch`	Auto-regenerate on file save (incremental)
`tokencap scan`	Scan outputs for leaked secrets (v1.4.0)
`tokencap audit`	View redaction audit trail (v1.4.0)
`tokencap upgrade`	Check for and install updates (v1.4.0 — only network command)
`tokencap version`	Show installed version (v1.4.0)

`tokencap make` — Build Intelligence

Runs all engines and writes the knowledge layer. Incremental by default since v1.3.0.

tokencap make                          # Incremental build (default)
tokencap make --full                   # Force full rebuild
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 cache (next build = full)
tokencap make --profile deep           # Use deep profile (forces full build)
tokencap make --no-diff                # Skip git diff snippets
tokencap make --no-contents            # Structure only (no file contents)

What tokencap make builds:

TOKENCAP.md            ← Project snapshot — paste into any AI
TOKENCAP_GRAPH.md      ← Dependency graph markdown
TOKENCAP_MEMORY.md     ← Developer context memory

.tokencap/brain/
  knowledge.json       ← Unified knowledge base
  brain-index.json     ← Cluster index

.tokencap/cache/
  hashes.cache.json    ← Incremental build cache (v1.3.0)

.tokencap/delta/       ← What changed this build (v1.3.0)
  brain.delta.json
  graph.delta.json
  constitution.delta.json
  agent.delta.json
  history/             ← Versioned snapshots (last 10)

.tokencap/agent/
  agent.json           ← Machine-readable agent intelligence
  (+ all agent files)

`tokencap agent` — Self-Loading Universal Context Layer

tokencap agent                     # Generate Self-Loading Universal Context Layer
tokencap agent --full              # All files + console summary
tokencap agent --architecture      # Architecture + tech stack only
tokencap agent --rules             # Rules + review rules only
tokencap agent --skills            # Skills + agent-pack only
tokencap agent --no-agents-file    # Skip generating root AGENTS.md
tokencap agent --execution         # Also generate Execution Contract (v1.1.0)
tokencap agent --execution --strict  # Strict mode: scope gates + enforcement

What gets generated

AGENTS.md (root)            ← AI discovers this automatically     (v1.0.0)

.tokencap/agent/

  START_HERE.md             ← Full onboarding — read after AGENTS.md (v1.0.0)
  agent-pack.md             ← Full intelligence — paste into any AI
  allowed-context.json      ← Topic → file glob map               (v1.0.0)
  model-instructions.md     ← Generic instructions for any model  (v1.0.0)
  context-manifest.json     ← Machine-readable intelligence index (v1.0.0)

  architecture.md           ← Architecture layers + critical chains
  rules.md                  ← Folder conventions + tech-specific rules
  review-rules.md           ← Which files to review together and why
  risk-map.md               ← CRITICAL / HIGH risk areas
  tech-stack.md             ← Detected languages, frameworks, databases
  skills.md                 ← Primary AI skill document
  agent.json                ← Machine-readable intelligence

  execution-contract/       ← Execution Contract (v1.1.0 — with --execution)
    execution-state.md
    engineering-principles.md
    decision-framework.md
    execution-ladder.md
    execution-scope.md
    verification-rules.md
    change-classification.md
    recovery-mode.md

`tokencap brain` — Project Brain

Query your repository intelligence without reading any code.

tokencap brain                     # Overview — all clusters + risk levels
tokencap brain auth                # Authentication cluster intelligence
tokencap brain payments            # Payments cluster intelligence
tokencap brain auth --impact       # Impact analysis: what breaks if auth changes?
tokencap brain auth --architecture # Architecture within the cluster
tokencap brain auth --review       # Review groupings for auth
tokencap brain auth --timeline     # Recent git changes in auth
tokencap brain auth --risk         # Risk breakdown for auth
tokencap brain auth --deps         # Dependency map for auth

`tokencap pack` — Context Pack

Token-budgeted, cluster-scoped context packs for any AI task.

tokencap pack auth                 # Topic-based: auth cluster context
tokencap pack payments             # Topic-based: payments cluster context
tokencap pack                      # Review mode, 20k token budget
tokencap pack --mode review        # Code review context (default)
tokencap pack --mode debug         # Debug investigation context
tokencap pack --mode architecture  # Architecture overview context
tokencap pack --mode minimal       # Minimal context (fastest)
tokencap pack auth --budget 10000  # Custom token budget

`tokencap diff` — Change Intelligence

tokencap diff                    # Analyze all working tree changes
tokencap diff --staged           # Staged changes only
tokencap diff --last             # Last commit
tokencap diff --json             # Export analyzed-diff.json
tokencap diff --pr               # Generate PR summary
tokencap diff --prompt           # Generate AI review prompt

`tokencap debug` — Debug Session

tokencap debug --start           # Start a new debug session
tokencap debug --start -- npm test  # Auto-capture failing command
tokencap debug                   # Regenerate debug handoff report
tokencap debug --log "message"   # Add timestamped event to timeline
tokencap debug --end             # End session and archive

`tokencap ask` — Smart Context Retrieval

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
tokencap ask "question" --budget 15000    # Custom token budget
tokencap ask "question" --json            # Also export context.json

Output Files

TOKENCAP.md                                  Project snapshot
TOKENCAP_GRAPH.md                            Dependency graph markdown
TOKENCAP_MEMORY.md                           Developer context memory

.tokencap/cache/
  hashes.cache.json                          Incremental build cache (v1.3.0)

.tokencap/delta/                             Incremental build deltas (v1.3.0)
  changed-files.json                         Files that changed this run
  affected-clusters.json                     Clusters that need updating
  dirty-nodes.json                           Graph nodes that are stale
  brain.delta.json                           Brain update summary
  graph.delta.json                           Graph update summary
  constitution.delta.json                    Constitution update summary
  agent.delta.json                           Agent update summary
  history/                                   Versioned delta snapshots (last 10)

.tokencap/agent/
  AGENTS.md (root)                           AI auto-discovery entry point
  START_HERE.md                              Onboarding entry point
  agent-pack.md                              All-in-one AI paste document
  allowed-context.json                       Topic → file glob map
  model-instructions.md                      Generic AI instructions
  context-manifest.json                      Machine-readable intelligence index
  architecture.md                            Architecture analysis
  rules.md                                   Project coding rules
  review-rules.md                            Code review groupings
  risk-map.md                                Risk area analysis
  tech-stack.md                              Technology detection
  skills.md                                  Agent skill document
  agent.json                                 Machine-readable intelligence

  execution-contract/                        Execution Contract (v1.1.0)
    execution-state.md                       STATE: Phase, scope, drift, confidence
    engineering-principles.md               ALWAYS: Philosophy + Minimal Solution First
    decision-framework.md                   PLAN: Decision tree before writing code
    execution-ladder.md                     DISCOVER: 12-step engineering workflow
    execution-scope.md                      IMPLEMENT: Scope tracker + Drift Detection
    verification-rules.md                   VERIFY: Done criteria + Confidence Rating
    change-classification.md               REVIEW: Behavior/Architecture/Bug/Refactor
    recovery-mode.md                        RECOVERY: Structured protocol when stuck

.tokencap/brain/
  knowledge.json                             Unified knowledge base
  brain-index.json                           Cluster index

.tokencap/constitution/                      Repository Constitution (v1.2.0)
  constitution.json                          Graph — single source of truth
  constitution.md                            Human-readable constitution
  constitution.yaml                          Structured export
  constitution-graph.html                    Interactive graph UI
  api-contracts.yaml                         Public API laws
  schema-invariants.yaml                     Database schema laws
  architecture-laws.md                       Architectural boundaries
  security-boundaries.md                     Security laws
  compliance-rules.md                        PCI-DSS, GDPR, HIPAA, SOC 2
  critical-flows.md                          Critical flow protection
  constitution-history/                      Timestamped snapshots

.tokencap/packs/
  review.md                                  Review mode context pack

.tokencap/diff/
  report.md                                  Change intelligence report

.tokencap/debug/
  active.md                                  Active debug handoff report

.tokencap/context/
  <topic>-context.md                         Smart context package
  <topic>-prompt.md                          Suggested AI prompt
  <topic>.json                               Machine-readable context

.tokencap/graph/
  graph.html                                 Interactive Obsidian-style graph viewer
  graph-data.json                            Full enriched graph JSON
  nodes.json                                 Node list
  edges.json                                 Edge list
  ai-graph-summary.md                        Architecture narrative
  graph-diff.md                              Graph change diff

.tokencap/security/                          Security Hardening (v1.4.0)
  redaction-log.json                         Redaction audit trail

.tokencap/quarantine/                        Quarantined files (v1.4.0)
  <timestamp>/                               Files moved here on scan failure

tokencap.security.yaml                       User security configuration (v1.4.0)
THREAT_MODEL.md                              Threat model documentation (v1.4.0)

Version History

Version	Highlight
v1.5.0	Self-Maintaining MCP Intelligence - MCP startup runs the initial build, keeps a watcher active for source and session-memory changes, and supports configuration for VS Code, Antigravity, and Codex.
v1.4.0	Security Hardening + Intelligence Service — Centralized redaction engine (38 patterns, 7 markers, entropy detection), `tokencap scan/audit/upgrade/version`, MCP live intelligence service (11 endpoints), zero secret leakage guarantee, THREAT_MODEL.md.
v1.3.0	Incremental Intelligence Engine — Analyze once. Update only what changed. Hash cache, bidirectional dependency walk, per-cluster updates, delta files, versioned history.
v1.2.0	Repository Constitution — Permanent engineering laws. Constitution Graph, stable rule IDs, IMMUTABLE severity, manual overrides, interactive graph UI, constitution score.
v1.1.0	Execution Contract — Scope Drift Detection, Engineering Discipline, Confidence Rating, Recovery Mode, Change Classification, Minimal Solution First
v1.0.0	Self-Loading Universal Context Layer —`AGENTS.md`, `START_HERE.md`, `allowed-context.json`, `model-instructions.md`, `context-manifest.json`. Topic-based `pack`.
v0.9	Project Brain —`tokencap brain`, unified `knowledge.json`, 6 intelligence modes
v0.8	Agent Intelligence — 8-phase pipeline,`agent-pack.md`, `agent.json`
v0.7	Smart Retrieval —`tokencap ask`, `tokencap context`, BFS graph traversal
v0.6	Graph Intelligence — Obsidian-style viewer, 13 node types, 4-tier risk, cluster detection
v0.5	`tokencap pack` — token-budgeted context compressor
v0.4	`tokencap diff` — semantic change intelligence, breaking change detection
v0.3	`tokencap debug` — AI debug handoff mode, auto-capture
v0.2	`TOKENCAP_GRAPH.md`, `TOKENCAP_MEMORY.md`

Supported Languages & Frameworks

Languages: JavaScript, TypeScript, Python, Go, Rust, Java, C#, PHP, Ruby, Swift, Kotlin

Frameworks: React, Next.js, Vue, Angular, Svelte, Express, Fastify, Koa, NestJS, Django, FastAPI, Spring, Laravel

Databases: PostgreSQL, MySQL, MongoDB, Redis, SQLite, DynamoDB, Supabase

ORMs: Prisma, Drizzle, TypeORM, Sequelize, Mongoose

Testing: Jest, Vitest, Mocha, Pytest, Go Test, Cargo Test

Auth: JWT, OAuth, NextAuth, Passport, Auth0

Cloud SDKs: AWS SDK, Google Cloud, Azure, Firebase

Payments: Stripe, PayPal, Paddle

Model Compatibility

Works with any AI model, IDE, or agent:

Tool	How to use
Claude / Claude Code	Reads`AGENTS.md` automatically
Gemini CLI / Antigravity	Reads`AGENTS.md` automatically
Claude Code	Native MCP via`tokencap mcp --init` + `tokencap mcp`
Cursor	Native MCP via`tokencap mcp --init` + `tokencap mcp`
Windsurf	Native MCP via`tokencap mcp --init` + `tokencap mcp`
Roo Code / Cline	Native MCP — copy config from`.tokencap/mcp/cline.json`
Claude Desktop	MCP via`.tokencap/mcp/claude-desktop.json` (uses `npx`)
VS Code	Native MCP via `tokencap mcp --init --client vscode`
Antigravity	Native MCP via `tokencap mcp --init --client antigravity`
Codex	Native MCP via `tokencap mcp --init --client codex`
ChatGPT / Gemini	Paste`agent-pack.md` (file-based fallback, always works)
Any model	Paste`agent-pack.md` (file-based fallback, always works)

Why Incremental Intelligence

Most AI tooling today focuses on making the model smarter or providing better context.

TokenCap v1.3.0 focuses on a different problem: making the intelligence layer efficient to maintain.

The intelligence is only as useful as it is current. If rebuilding it takes too long — in watch mode, in CI, in a tight feedback loop — developers stop running it.

Incremental Intelligence makes tokencap make as cheap as the change that triggered it.

1 file changed  →  1–2 clusters updated  →  <100ms
10 files changed → 3–4 clusters updated  →  <500ms
100 files changed → full build fallback  →  same as before

The philosophy:

Analyze once. Update only what changed. Never rebuild what hasn't.

License

MIT

TokenCap v1.5.0 - Self-Maintaining MCP Intelligence

TokenCap

Vansh Arora

TokenCap

The Problem

The Solution

Quick Start

What's New in v1.5.0 - Self-Maintaining MCP Intelligence

What's New in v1.4.0 — Repository Intelligence Service

11 MCP Endpoints

Setup — two steps

All CLI flags

Token savings

IDE compatibility

What's New in v1.4.0 — Security Hardening Engine

What gets caught

What's safe (false positive prevention)

Redaction markers

New CLI Commands

Network policy

Configuration

Security architecture

What's New in v1.3.0 — Incremental Intelligence Engine

How It Works

New CLI Flags

Delta Files

Zero-Change Scenario

Incremental Build Output Example

Cache Integrity

What's New in v1.2.0 — Repository Constitution

Generate It

What It Generates

Constitution Score

Rule Structure

Manual Overrides

CLI Commands

Version Summary

Getting Started

5 Commands to Remember

All Commands

tokencap make — Build Intelligence

tokencap agent — Self-Loading Universal Context Layer

What gets generated

tokencap brain — Project Brain

tokencap pack — Context Pack

tokencap diff — Change Intelligence

tokencap debug — Debug Session

tokencap ask — Smart Context Retrieval

Output Files

Version History

Supported Languages & Frameworks

Model Compatibility

Why Incremental Intelligence

License

`tokencap make` — Build Intelligence

`tokencap agent` — Self-Loading Universal Context Layer

`tokencap brain` — Project Brain

`tokencap pack` — Context Pack

`tokencap diff` — Change Intelligence

`tokencap debug` — Debug Session

`tokencap ask` — Smart Context Retrieval