No setup required to start.
Use the skill alone — paste into Claude, works immediately.
Add Python 3.7+ to unlock auto-manifest generation.
| Tool | What it cuts | Install needed |
|---|---|---|
| 🪨 Caveman | Output tokens (~75%) | One command |
| 🔬 code-review-graph | Input tokens (8.2x²) | pip + Python 3.10+ |
| 🗜️ Context Optimizer | Input tokens (see benchmarks) | Zero to start |
² code-review-graph benchmarks
Claude has a 200K token context window — but burning 20K tokens just to show a directory structure is wasteful. This toolkit teaches Claude to fetch only what it needs, compress what it sees, and reason structurally instead of reading raw files.
No API hacks. No leaked code. No reverse engineering. Just official Claude features (Custom Instructions + Projects + Knowledge) and a lightweight local indexer.
| Project | Files | Peak reduction | Avg reduction |
|---|---|---|---|
| shadcn/ui (public) | 55 components | 116x | ~82x |
| Health Sync (private React + Firebase) | 130 files | 37x | ~24x |
| Task | Files needed | With optimizer | Without | Reduction |
|---|---|---|---|---|
| Add variant to Button | 1 (button.tsx) |
397 tokens | 46,071 | 116x |
| Fix focus ring accessibility | 2 (button + input) |
559 tokens | 46,071 | 82x |
| Add size prop to Card | 1 (card.tsx) |
538 tokens | 46,071 | 85x |
| Update Dialog behavior | 1 (dialog.tsx) |
971 tokens | 46,071 | 47x |
| Average | ~82x |
| Task | With optimizer | Without | Reduction |
|---|---|---|---|
| Fix auth bug | 4,629 tokens | 175,229 | 37x |
| Debug food scanner | 6,656 tokens | 175,229 | 26x |
| Add dashboard widget | 8,805 tokens | 175,229 | 20x |
| Update nutrition UI | 13,363 tokens | 175,229 | 13x |
| Average | ~24x |
Methodology: file sizes ÷ 4 (standard approximation). "Without" = all files in scope. Reproduce: python3 tools/context_mapper.py
Without Context Optimizer, Claude reads every file it thinks might be relevant — often 10–15 files before answering.
With Context Optimizer, Claude reads the manifest first, fetches 2–3 targeted files, then answers. Same result. Fraction of the context.
Paste skill/claude-custom-instructions.md into Claude Custom Instructions or any chat. Done.
- Copy the contents of
skill/claude-custom-instructions.md - Paste into Claude Settings → Custom Instructions
- Claude immediately starts reasoning from structure, not scanning files
npm install -g @anshmaj121/context-optimizer
context-optimizer init ./your-project
python3 tools/context_mapper.py ./your-projectUpload the generated CONTEXT_MANIFEST.md to a Claude Project as Knowledge. Every session after that runs lean.
macOS/Linux:
npx @anshmaj121/context-optimizer init ./your-projectalso works.
Windows: use the two-line form above — npx has a known bin resolution bug with scoped packages on Windows.
Your Project
│
▼
context_mapper.py ──► CONTEXT_MANIFEST.md
│
▼
Claude Project Knowledge
│
▼
skill/claude-custom-instructions.md
(via Custom Instructions or CLAUDE.md)
│
▼
Token-Efficient Claude Sessions
1. CONTEXT_MANIFEST.md — A structural index of your codebase: file paths, languages, line counts, import graphs, and blast-radius data. Claude reads this instead of scanning directories.
2. Core Skill — Custom instructions that enforce structural reasoning, limit file fetches to 3/turn, and compress all output into a strict format.
3. Session Activator — A one-click prompt to paste at the start of any session when you can't use Custom Instructions.
context-optimizer/
├── context-optimizer-skill/
│ ├── SKILL.md # Skill with YAML frontmatter (for skill registries)
│ └── LICENSE.txt
├── skill/
│ └── claude-custom-instructions.md # Paste into Claude Custom Instructions
├── prompt/
│ └── one-click-vertical-prompt.md # Paste at start of any session
├── scripts/
│ └── install.sh # Full-stack installer (idempotent)
├── tools/
│ └── context_mapper.py # Manifest + dependency graph generator
├── .claude/
│ ├── COMMON_MISTAKES.md # Project-specific bug history
│ ├── QUICK_START.md # Daily commands
│ └── ARCHITECTURE_MAP.md # High-level routing & layers
├── .claudeignore # Files excluded from Claude's context
└── docs/
├── learnings/ # Session insights (gitignored)
└── archive/ # Old versions (gitignored)
- Run
python3 tools/context_mapper.py /your/project - Upload
CONTEXT_MANIFEST.mdto a Claude Project as Knowledge - Add
skill/claude-custom-instructions.mdto Project Instructions - Start chatting — Claude will reason from the manifest automatically
- Go to Claude Settings → Custom Instructions
- Paste the contents of
skill/claude-custom-instructions.md - For each project, paste
CONTEXT_MANIFEST.mdinto the chat or upload it
- Open any Claude chat
- Paste
prompt/one-click-vertical-prompt.mdas your first message - Claude confirms:
✅ Context Optimizer active. - Upload or paste
CONTEXT_MANIFEST.mdand start your task
Run the installer — it auto-detects .claude/ and injects the skill into CLAUDE.md:
./scripts/install.sh /your/project# Basic usage
python3 tools/context_mapper.py /path/to/project
# Blast-radius analysis (find all files affected by a change)
python3 tools/context_mapper.py /path/to/project --blast-radius src/auth.py,src/models.pyOutput files:
CONTEXT_MANIFEST.md— Human + AI readable manifest.claude/graph.json— Machine-readable dependency graph
| Command | Effect |
|---|---|
RELOAD CONTEXT OPTIMIZER |
Reset all rules for this session |
MAX_FILES: 5 |
Allow up to 5 files per turn |
BUDGET: 2000 |
Raise token budget to 2,000 |
COMPRESSION: lite |
Less aggressive compression |
TEMP VERBOSE |
One-turn verbose mode, then revert |
See CONTRIBUTING.md. PRs welcome — especially for new language parsers in context_mapper.py.
| Tool | Role |
|---|---|
| Caveman | Cuts Claude output tokens (~75%) |
| context-optimizer | Cuts Claude input tokens (13–116x) |
| code-review-graph | Input tokens for large monorepos with git history (8.2x) |
Best results: install Caveman + Context Optimizer together. They solve opposite sides of the same problem.
MIT — see LICENSE.