context-optimizer

5–27x fewer tokens. No setup required to start.

Use the skill alone — no install needed, works anywhere Claude runs.
Add Python 3.7+ to unlock auto-manifest generation.

² code-review-graph benchmarks

Why This Exists

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.

Real-World Savings

How it works in practice

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.

Quick Start (30 seconds)

# 1. Clone the repo
git clone https://github.com/anshmajumdar121/context-optimizer.git
cd context-optimizer

# 2. Run the installer (idempotent, safe to re-run)
chmod +x scripts/install.sh
./scripts/install.sh /path/to/your/project

# 3. Generate a structural manifest of your project
python3 tools/context_mapper.py /path/to/your/project

# 4. Upload CONTEXT_MANIFEST.md to a Claude Project (optional but recommended)

# 5. Paste the one-click prompt into Claude Desktop/Web
cat prompt/one-click-vertical-prompt.md | pbcopy  # macOS
cat prompt/one-click-vertical-prompt.md | xclip   # Linux

How It Works

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

The Three Pillars

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.

File Structure

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)

Usage Guide

Option A: Claude Projects (Recommended)

1. Run python3 tools/context_mapper.py /your/project
2. Upload CONTEXT_MANIFEST.md to a Claude Project as Knowledge
3. Add skill/claude-custom-instructions.md to Project Instructions
4. Start chatting — Claude will reason from the manifest automatically

Option B: Custom Instructions (Global)

1. Go to Claude Settings → Custom Instructions
2. Paste the contents of skill/claude-custom-instructions.md
3. For each project, paste CONTEXT_MANIFEST.md into the chat or upload it

Option C: Per-Session Activation

1. Open any Claude chat
2. Paste prompt/one-click-vertical-prompt.md as your first message
3. Claude confirms: ✅ Context Optimizer active.
4. Upload or paste CONTEXT_MANIFEST.md and start your task

Option D: Claude Code / CLAUDE.md

Run the installer — it auto-detects .claude/ and injects the skill into CLAUDE.md:

./scripts/install.sh /your/project

Manifest Generator

# 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.py

Output files:

• CONTEXT_MANIFEST.md — Human + AI readable manifest
• .claude/graph.json — Machine-readable dependency graph

Overrides & Controls

Contributing

See CONTRIBUTING.md. PRs welcome — especially for new language parsers in context_mapper.py.

License

MIT — see LICENSE.