terminal

CLAUDE_CTX
OVERVIEW THE PROBLEM COMMANDS INSTALL TEAMS GITHUB ↗
v1.1.4 · Stable · MIT Licensed

STOP PAYING
FOR NOISE

claudectx surgically removes redundant tokens from every Claude Code request — cutting costs by up to 80% while preserving 100% of accuracy.

13 commands · Zero config changes · Works in 60 seconds

$ npm install -g claudectx

Or try without installing: npx claudectx analyze

0% AVG TOKEN REDUCTION
0 CLI COMMANDS
0 TESTS PASSING
MIT OPEN SOURCE

The Root Cause

Where Your Tokens Actually Go

A typical Claude Code session costs $2–$15. Most of it is wasted on context you never needed.

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 BIGGEST WIN 6,800–14,000 22–46% YES
MEMORY.md / memory files 3,300 11% YES
Conversation history (grows) 2,000–40,000 7–57% YES

Teal rows = fixable with claudectx

description
12,200
EXTRA TOKENS/REQUEST

Bloated CLAUDE.md injected on every single request — even for a one-line change.

claudectx optimize --claudemd
folder_off
40–60%
SEARCH TOKENS WASTED

No .claudeignore means Claude reads node_modules, lock files, and build artifacts on every search.

claudectx optimize --ignorefile
file_open
97%
TOKENS SAVED PER READ

Full file reads for small questions. claudectx mcp lets Claude read one function instead of the whole file.

claudectx mcp --install

Terminal Interface

Real Commands. Real Output.

Watch claudectx analyse your project, optimize it, and report the savings.

bash — claudectx
LIVE

Token Efficiency

Before vs After

Same project. Same Claude. One command changed everything.

BEFORE — RAW REQUEST 18,432 tokens
[CLAUDE.md] 7,841 tokens — injected every request
[CLAUDE.md] dynamic timestamp on line 3 — breaks caching
[search] scanned node_modules/ (11,200 results, 0 useful)
[read] auth.py — 847 lines (needed: function on line 42)
[MEMORY.md] 2,800 tokens — stale entries from 3 months ago
[session] no caching — paying full price every turn
[task] Fix the auth bug in login.py line 42
[history] 4,200 tokens — includes closed tasks
def authenticate(user, password):
return db.query(user, password)
EST. COST / REQUEST $0.054
content_cut
AFTER — CLAUDECTX 3,740 tokens
[CLAUDE.md] 1,840 tokens core — refs loaded on demand
⌛ cache hit — timestamp removed, caching active
⌛ .claudeignore — node_modules excluded
⌛ smart_read — line 42-58 only (11 lines)
⌛ MEMORY.md pruned — 180 tokens, current context only
[task] Fix the auth bug in login.py line 42
def authenticate(user, password):
return db.query(user, password)
EST. COST / REQUEST $0.012
79.7%
Tokens Saved
$0.042
Saved Per Request
~$126
Saved / Month at 3k req/day

Core Capabilities

Six Ways to Kill Token Waste

content_cut
Intelligent
CLAUDE.md
Optimization

Parses your CLAUDE.md by ## sections, keeps core rules inline (<2K tokens), moves reference docs to demand-loaded @file references. Up to 12,200 tokens saved per request.

claudectx optimize --claudemd
api 97% FEWER TOKENS
Symbol-Level MCP Server

Read one function instead of a whole file. smart_read, search_symbols, index_project — Claude gets exactly what it needs, nothing more.

claudectx mcp --install
monitor_heart
Live Token Dashboard

Real-time terminal UI: burn rate, cache hit rate, most-read files — while Claude is coding.

claudectx watch
memory arrow_outward
Cross-Session Memory

8,000-token session compressed to ~180 tokens in MEMORY.md. 97.8% reduction. Key context survives across sessions.

claudectx compress
cached
Prompt Cache Warmup

Pre-warm the Anthropic cache before you start coding. First request = cache hit, not a cold miss paying 10×.

claudectx warmup
devices
Multi-Assistant Convert

Export your CLAUDE.md to Cursor, Copilot, or Windsurf in one command. Same instructions, every AI tool.

claudectx convert --to cursor

Quick Start

Up and Running in 60 Seconds

Three commands. No config files. No accounts required.

01
Install globally

Or skip the install entirely and try it right now.

npm install -g claudectx
npx claudectx analyze # no install needed
02
Analyse your project

See token breakdown, cost per request, and exactly what to fix.

claudectx analyze
03
Auto-fix everything

All changes are backed up automatically before anything is modified.

claudectx optimize --apply
shield Every write auto-backed up claudectx revert
preview Dry-run on all commands --dry-run
verified 296 tests · 0 lint errors

Requires Node.js 18+ · Also available via Homebrew and pip · 100% local — no data leaves your machine

Command Reference

13 Commands. One Purpose.

Everything you need to control, compress, and understand your context window.

analyze CORE

See exactly where your tokens go. Cost per request, waste patterns, and optimization opportunities — all in one table.

claudectx analyze
--path · --json · --model · --watch
optimize CORE

Auto-fix token waste. CLAUDE.md splitter, .claudeignore generator, cache advisor, hooks installer. One command, everything fixed.

claudectx optimize --apply
--dry-run · --claudemd · --ignorefile · --cache
watch LIVE

Real-time terminal dashboard showing token burn rate, cache hit rate, and most-read files while Claude is working.

claudectx watch
--session · --clear
mcp SERVER

Smart MCP server: Claude reads one function instead of a whole file. Up to 97% fewer tokens per read via smart_read, search_symbols.

claudectx mcp --install
--install · stdio mode
compress MEMORY

Compress the full session JSONL into a compact MEMORY.md entry. A typical 8,000-token session → ~180 tokens. 97.8% reduction.

claudectx compress
--auto · --prune --days 30 · --api-key
report ANALYTICS

7/30-day usage analytics: sessions, requests, input tokens, cache hit rate, cost estimate, and top files by read count.

claudectx report --days 30
--json · --markdown · --model
open_in_new Full documentation on GitHub

For Engineering Leads

Know Where the Budget Goes

claudectx teams gives per-developer cost attribution without sharing session content or prompts.

STEP 1 — EACH DEVELOPER
person

Each developer runs this locally on their own machine. Generates a lightweight JSON file — no session content, just aggregated token counts.

claudectx teams export

→ ~/.claudectx/team-export-{date}.json

STEP 2 — ENGINEERING LEAD
group

Collect the JSON files in a shared directory. Aggregate them to see per-developer spend, cache hit rate, avg request size, and top shared waste files.

claudectx teams aggregate
--dir ./reports/
PRIVACY
visibility_off

Use --anonymize to replace identities with "Dev 1, Dev 2..." before sharing. No prompts, no conversation history — only token counts.

claudectx teams aggregate
--anonymize
SAMPLE OUTPUT — claudectx teams aggregate --dir ./reports/ --anonymize
Dev 1 $12.40/week · cache hit 68% · avg req 4,200 tokens · top file: CLAUDE.md
Dev 2 $8.91/week · cache hit 54% · avg req 3,100 tokens · top file: models.py
Dev 3 $4.22/week · cache hit 81% · avg req 1,800 tokens · top file: auth.ts
TEAM $25.53/week · cache hit 67% · potential savings: $8.40/week with claudectx optimize

The Full Picture

How It All Fits Together

WITHOUT CLAUDECTX
close
Every request: 12,400-token CLAUDE.md
paying for every byte, every time
close
No caching — pay full price each turn
10× cost on static context
close
Full file reads for every question
reading 847 lines to find line 42
close
Session forgotten at end
starting from zero every session
$2–$15
typical daily cost
WITH CLAUDECTX
check_circle
Every request: 1,800-token CLAUDE.md core
refs loaded on demand via @file
check_circle
Cache hit rate: 70%+ after warmup
static context served at 10× discount
check_circle
smart_read: symbol-level only
97% fewer tokens per file read
check_circle
claudectx compress → 187 tokens
MEMORY.md carries context forward
$0.40–$3
typical daily cost (same workload)

EVERY TOKEN COSTS MONEY.
SPEND WISELY.

"The fastest path to cheaper, faster Claude calls is feeding it less. claudectx does the cutting."

$ npx claudectx analyze

No install. Runs in your project directory right now.

READY
ENGINE: CLAUDE 4
CTX-SAVED: 80% V 1.1.4