Why claudectx?

A typical Claude Code session costs $2–$15 in tokens. Most of it is wasted:

| Problem | Impact | Fix | |---|---|---| | Bloated CLAUDE.md injected every request | 6,000–14,000 extra tokens/request | claudectx optimize --claudemd | | No .claudeignore — reads node_modules/ | 40–60% of search tokens wasted | claudectx optimize --ignorefile | | Full file reads for small questions | 70% overhead from unnecessary lines | claudectx mcp | | No prompt caching configured | Paying 10× for static context | claudectx optimize --cache | | No cross-session memory | Repeating the same context every session | claudectx compress | | Dead @refs and stale sections in CLAUDE.md | Silent token waste on every request | claudectx drift | | Unknown cost before running a big task | Surprise bills after the fact | claudectx budget | | Cache cold at session start | First request always a full miss | claudectx warmup | | No visibility into team-wide spend | Can't attribute cost across devs | claudectx teams |

Where your tokens actually go

| Component | Typical Tokens | % of Total | Fixable? | |---|---|---|---| | Claude Code system prompt | 4,200 | 14% | No | | Tool definitions (built-in) | 2,100 | 7% | No | | MCP tool schemas | 1,980 | 7% | Partially | | CLAUDE.md | 6,800–14,000 | 22–46% | YES — biggest win | | MEMORY.md / memory files | 3,300 | 11% | YES | | Conversation history (grows) | 2,000–40,000 | 7–57% | YES |

Quick Start

# No install needed — try it immediately
npx claudectx analyze

# Fix everything automatically
npx claudectx optimize --apply

# See what's happening in real time while Claude is coding
claudectx watch

# After your session: compress it into a tiny MEMORY.md entry
claudectx compress

# Review your token spend for the last 7 days
claudectx report

# --- v1.1.0 additions ---

# Know the cost before you start a task
claudectx budget "src/**/*.ts" "tests/**/*.ts"

# Pre-warm your prompt cache so the first request is free
claudectx warmup --api-key $ANTHROPIC_API_KEY

# Find dead references and stale sections in CLAUDE.md
claudectx drift

# Convert CLAUDE.md to Cursor / Copilot / Windsurf format
claudectx convert --to cursor

# Export your usage data for team-wide cost attribution
claudectx teams export

# --- Safety: every command that modifies files backs up automatically ---

# See all automatic backups
claudectx revert --list

# Restore any backup (also backs up current file so you can undo the undo)
claudectx revert --id <id>

Installation

# npm (recommended)
npm install -g claudectx

# Homebrew
brew tap Horilla/claudectx
brew install claudectx

# pip (Python projects)
pip install claudectx-py
# then: npm install -g claudectx  (the npm package is still required)

Commands

claudectx analyze — See exactly where your tokens go

╔══════════════════════════════════════════════════════════════╗
║               claudectx — Context Analysis                   ║
║               Project: /Users/you/my-project                 ║
╠══════════════════════════════════════════════════════════════╣
║  Tokens per request: 18,432    Est. session cost: $1.84      ║
║  Model: claude-sonnet-4-6      Context used: 1.8% of 1M     ║
╠═══════════════════════════════╦══════════╦═══════╦══════════╣
║ Component                     ║  Tokens  ║  Cost ║  Status  ║
╠═══════════════════════════════╬══════════╬═══════╬══════════╣
║ System prompt (built-in)      ║   4,200  ║ $0.01 ║    ✓     ║
║ Tool definitions (built-in)   ║   2,100  ║ $0.01 ║    ✓     ║
║ CLAUDE.md (./CLAUDE.md)       ║   7,841  ║ $0.02 ║    ⚠     ║
║ MEMORY.md                     ║   2,551  ║ $0.01 ║    ✓     ║
╠═══════════════════════════════╬══════════╬═══════╬══════════╣
║ TOTAL (per request)           ║  18,432  ║ $0.06 ║          ║
╚═══════════════════════════════╩══════════╩═══════╩══════════╝

⚠  3 optimization opportunities found:

  [1] CLAUDE.md is 7,841 tokens — 292% over the 2,000 token recommendation
      → Run `claudectx optimize --claudemd` to split into demand-loaded files
      → Potential savings: ~5,841 tokens/request (~$3.51/hour at 60 req/hr)

  [2] No .claudeignore file found
      → Run `claudectx optimize --ignorefile` to generate one

  [3] CLAUDE.md contains dynamic timestamp on line 3
      → Breaks prompt caching — run `claudectx optimize --cache` to fix

claudectx analyze                        # Analyze current directory
claudectx analyze --path /path/to/proj  # Analyze specific path
claudectx analyze --json                 # Raw JSON output
claudectx analyze --model sonnet         # Calculate for specific model
claudectx analyze --watch                # Re-run on file changes

claudectx optimize — Auto-fix token waste

claudectx optimize                    # Interactive — confirm each change
claudectx optimize --apply            # Apply all fixes without prompting
claudectx optimize --dry-run          # Preview changes without applying
claudectx optimize --claudemd         # Only optimize CLAUDE.md
claudectx optimize --ignorefile       # Only generate .claudeignore
claudectx optimize --cache            # Only fix cache-busting content
claudectx optimize --hooks            # Only install session hooks

What it does:

• CLAUDE.md splitter — Parses your CLAUDE.md by ## sections, keeps core rules inline (<2K tokens), moves reference docs to .claude/ loaded on demand with @file references.
• .claudeignore generator — Detects your project type (Node, Python, Rust, Go) and generates a .claudeignore with sensible defaults.
• Cache advisor — Finds date strings, timestamps, and other patterns that break prompt caching and comments them out.
• Hooks installer — Installs a PostToolUse hook in .claude/settings.local.json so claudectx watch can track files in real time.

Safety: optimize backs up your CLAUDE.md automatically before any changes. Run claudectx revert --list to restore.

claudectx watch — Live token dashboard

Real-time terminal UI showing token burn rate, cache hit rate, and most-read files while Claude Code is running.

claudectx watch                    # Launch dashboard
claudectx watch --session <id>     # Watch a specific session
claudectx watch --clear            # Clear the read log and exit

The dashboard auto-refreshes every 2 seconds and updates instantly when a new file is read (requires hooks from claudectx optimize --hooks).

claudectx mcp — Smart MCP server

An MCP server that lets Claude read just one function or class from a file instead of the whole thing — up to 97% fewer tokens per read.

claudectx mcp                  # Start MCP server (stdio)
claudectx mcp --install        # Auto-add to .claude/settings.json

Tools provided to Claude:

• smart_read — Read a specific symbol (function, class, method) by name, or a line range
• search_symbols — Find where a symbol is defined without reading any files
• index_project — Build the symbol index for the current project

Configure manually in .claude/settings.json:

{
  "mcpServers": {
    "claudectx": {
      "command": "claudectx",
      "args": ["mcp"],
      "type": "stdio"
    }
  }
}

claudectx compress — Session memory compression

Compress the full session JSONL into a compact MEMORY.md entry at the end of your session. Uses claude-haiku if ANTHROPIC_API_KEY is set, otherwise falls back to a structured heuristic summary.

claudectx compress                        # Compress most recent session
claudectx compress --session <id>         # Compress specific session
claudectx compress --auto                 # Non-interactive (for hooks)
claudectx compress --prune --days 30      # Also prune entries older than 30 days
claudectx compress --api-key <key>        # Provide API key explicitly

A typical 8,000-token session compresses to ~180 tokens — 97.8% reduction.

Safety: compress --prune asks for confirmation before deleting entries and backs up MEMORY.md first. Run claudectx revert --list to restore.

claudectx report — Usage analytics

claudectx report                # Last 7 days (plain text)
claudectx report --days 30      # Last 30 days
claudectx report --json         # JSON output
claudectx report --markdown     # Markdown output
claudectx report --model opus   # Cost estimate for a different model

claudectx report — 7-day summary (2026-04-04 → 2026-04-11)
══════════════════════════════════════════════════════════════════════

TOTALS
────────────────────────────
  Sessions:              23
  Requests:              847
  Input tokens:          2,341,200
  Output tokens:         318,400
  Cache reads:           1,204,000  (51% hit rate)
  Total cost (est.):     $4.87
  Avg cost/session:      $0.21
  Avg tokens/request:    2,766

DAILY USAGE
────────────────────────────
  2026-04-11  ████████████████░░  412K in  $1.02  (5 sess)
  2026-04-10  █████████░░░░░░░░░  234K in  $0.58  (4 sess)
  ...

claudectx budget — Know the cost before you start

Before running a big task, see exactly which files will be read, how many tokens they'll consume, and what it'll cost.

claudectx budget "src/**/*.ts"                        # Estimate all TypeScript files
claudectx budget "**/*.py" --threshold 20000          # Warn if total exceeds 20K tokens
claudectx budget "src/**" --model opus --json         # JSON output for scripting

Output shows per-file token counts, cache hit likelihood (based on your recent reads), total cost estimate, and .claudeignore recommendations for files that are large but rarely useful.

claudectx warmup — Pre-warm the prompt cache

Start each session with a cache hit instead of a full miss. Sends a silent priming request to Anthropic so your CLAUDE.md is cached before Claude Code touches it.

claudectx warmup --api-key $ANTHROPIC_API_KEY          # 5-min cache TTL (default)
claudectx warmup --ttl 60 --api-key $ANTHROPIC_API_KEY # 60-min extended TTL (2× write cost)
claudectx warmup --model sonnet --api-key $ANTHROPIC_API_KEY  # use a specific model
claudectx warmup --cron "0 9 * * 1-5"                 # Install as weekday 9am cron job
claudectx warmup --json                                # JSON output for scripting

Reports tokens warmed, write cost, savings per cache hit, and break-even request count.

Note on --cron: The API key is not embedded in the cron job. At runtime, the job reads ANTHROPIC_API_KEY from your environment. Set it in ~/.profile or ~/.zshenv so cron can see it.

claudectx drift — CLAUDE.md stays fresh, not stale

Over time CLAUDE.md accumulates dead references and sections nobody reads. drift finds them.

claudectx drift                      # Scan current project
claudectx drift --days 14            # Use 14-day read window (default: 30)
claudectx drift --fix                # Interactively remove flagged lines (creates CLAUDE.md.bak first)
claudectx drift --json               # JSON output
claudectx drift --path /other/proj  # Scan a different project directory

Detects 4 types of drift:

| Type | Example | |---|---| | Dead @ref | @src/old-service.ts — file deleted | | Git-deleted mention | legacy-auth.py appears in prose but was removed in git | | Stale section | ## Android Setup — zero reads in 30 days | | Dead inline path | src/utils/helper.py mentioned in text, no longer exists |

claudectx hooks — Hook marketplace

Install named, pre-configured hooks beyond the basic read logger.

claudectx hooks list                                        # Show all available hooks
claudectx hooks add auto-compress                           # Install with default threshold (50k tokens)
claudectx hooks add auto-compress --config threshold=30000  # Custom token threshold
claudectx hooks add slack-digest --config webhookUrl=https://hooks.slack.com/...
claudectx hooks remove slack-digest                         # Remove an installed hook
claudectx hooks status                                      # Show what's installed

Built-in hooks:

| Hook | Trigger | Config | What it does | |---|---|---|---| | auto-compress | PostToolUse (Read) | threshold (default: 50000) | Runs claudectx compress after each session | | daily-budget | PreToolUse | (none) | Reports today's spend before each tool call | | slack-digest | Stop | webhookUrl (required) | Posts session report to a Slack webhook | | session-warmup | PostToolUse (Read) | (none) | Re-warms the cache; reads ANTHROPIC_API_KEY from env |

Security note: Hooks that need an API key (compress, warmup) read ANTHROPIC_API_KEY from your environment — no secrets are stored in .claude/settings.local.json.

Safety: hooks remove asks for confirmation and backs up .claude/settings.local.json before removing. Run claudectx revert --list to restore.

claudectx convert — Use your CLAUDE.md everywhere

You wrote great instructions for Claude. Use them with Cursor, Copilot, or Windsurf too.

claudectx convert --to cursor         # → .cursor/rules/<section>.mdc (one per ## section)
claudectx convert --to copilot        # → .github/copilot-instructions.md
claudectx convert --to windsurf       # → .windsurfrules
claudectx convert --to cursor --dry-run  # Preview without writing

Each ## section in CLAUDE.md becomes a separate Cursor .mdc file with alwaysApply: true frontmatter. @file references are stripped for assistants that don't support them.

Safety: convert backs up any existing target file before overwriting. Run claudectx revert --list to restore.

claudectx teams — Multi-developer cost attribution

See where the money goes across your whole team — without sharing session content.

# Step 1: each developer runs this on their own machine
claudectx teams export                           # Default: last 30 days, sonnet pricing
claudectx teams export --days 7 --model haiku   # Custom window and model

# Step 2: collect the JSON files in a shared directory, then aggregate
claudectx teams aggregate --dir ./reports/
claudectx teams aggregate --dir ./reports/ --anonymize  # Replace names with Dev 1, Dev 2...
claudectx teams aggregate --dir ./reports/ --json       # Machine-readable JSON

# Optional: copy your export to a shared location
claudectx teams share --to /shared/reports/

Output shows per-developer spend, cache hit rate, avg request size, and top shared files. Exports are lightweight JSON — no session content, no prompts, just aggregated token counts.

claudectx revert — Restore any backup

Every command that modifies your files creates an automatic backup in ~/.claudectx/backups/ before touching anything. If something goes wrong — or you just changed your mind — you can always recover.

claudectx revert --list         # See all backups with timestamps and size
claudectx revert --id <id>      # Restore a specific backup
claudectx revert                # Interactive: pick from list
claudectx revert --file CLAUDE.md  # Filter to backups of one file

Example output of claudectx revert --list:

claudectx — Backup History
══════════════════════════════════════════════════════════════════
  ID                          File                Command     When
──────────────────────────────────────────────────────────────────
  20260412T083012m445-1842...  CLAUDE.md           optimize    2 hours ago
  20260411T211533m102-9913...  MEMORY.md           compress    1 day ago
  20260411T094201m773-3371...  copilot-instr...    convert     2 days ago

When you restore, claudectx backs up the current file first — so you can undo the undo:

⚠  This will overwrite /path/to/CLAUDE.md with the backup from 2 hours ago.
   Your current file will be backed up first (so you can undo this).
   Restore? [y/N]

Safety: Backups are kept for the 50 most recent operations, then auto-pruned. They are stored only on your local machine.

Which commands create backups automatically:

| Command | What gets backed up | |---|---| | optimize --claudemd | CLAUDE.md (before split) | | optimize --cache | CLAUDE.md (before cache-busting lines are commented out) | | convert --to X | Existing Cursor/Copilot/Windsurf config (if it exists) | | compress --prune | MEMORY.md (before old entries are deleted) | | hooks remove | .claude/settings.local.json (before hook is removed) | | drift --fix | CLAUDE.md.bak (existing behaviour, now also in manifest) |

How it all fits together

Before claudectx:                    After claudectx:
─────────────────────────────        ─────────────────────────────
Every request:                       Every request:
  CLAUDE.md: 12,400 tokens     →       CLAUDE.md core: 1,800 tokens
  No caching: pay full price   →       Cache hit rate: 70%+
  Full file reads every time   →       smart_read: symbol-level only

End of session:                      End of session:
  Session forgotten            →       claudectx compress → 187 tokens
  Start from scratch next time →       MEMORY.md carries key context forward

Token Savings — Share Your Results

Join the Token Savings Hall of Fame — share your before/after numbers and see real results from other developers.

Contributing

PRs welcome. Please read CONTRIBUTING.md first.

git clone https://github.com/Horilla/claudectx.git
cd claudectx
npm install
npm run build
npm test          # 293 tests, should all pass
npm run lint      # 0 errors expected

License

MIT — see LICENSE