Claude Code optimizer

Put Your CLAUDE.md On a Diet.

Split bloated instruction files into a tiny routing index (always loaded) and topic-specific rule files (loaded on demand). Save context tokens every session.

Get started Read the Handbook

Analyze

npx @mcptoolshop/claude-rules analyze # File: CLAUDE.md (258 lines, ~2388 tokens) # Proposed extractions: 8 sections # Savings: 91% per session

Split

npx @mcptoolshop/claude-rules split # Interactive — approve each extraction # Generates index.json + rule files

Stats

npx @mcptoolshop/claude-rules stats # Always loaded: 320 tokens # On-demand total: 2180 tokens # Savings: 91%

Features

Everything that makes your CLAUDE.md leaner.

Section Scoring

Analyze your CLAUDE.md and see exactly which sections are core (must stay inline) and which can be extracted. Priority classification uses heading signals, content length, and domain markers.

Interactive Extraction

The split command walks you through each proposed extraction. Preview the rule file, approve or skip. Like eslint --fix for your instruction files.

Dispatch Table

Generates index.json with keywords, patterns, priority tiers, and trigger phases. The agent reads the index and loads rule files on demand.

Frontmatter Routing

Each extracted rule file carries its own routing metadata as frontmatter. Keywords, patterns, priority, triggers — the source of truth for the dispatch table.

Drift Detection

The validate command catches stale indexes, missing files, orphaned rules, empty keywords, and frontmatter drift. Keeps your rules healthy over time.

Token Budget Dashboard

See the physics of your system: always-loaded cost, on-demand total, average task load, and savings percentage. Know exactly what you are paying.

Quick Start

Analyze

# Score your CLAUDE.md sections
npx @mcptoolshop/claude-rules analyze

# Or point to a specific file
npx @mcptoolshop/claude-rules analyze .claude/CLAUDE.md

Split

# Interactive extraction
npx @mcptoolshop/claude-rules split

# Preview without writing
npx @mcptoolshop/claude-rules split --dry-run

Validate & Stats

# Lint your rules directory
npx @mcptoolshop/claude-rules validate

# Token budget dashboard
npx @mcptoolshop/claude-rules stats

Priority Tiers

Three tiers with clear semantics. No ambiguity about what loads and when.

Tier

Behavior

Example

core

Always inline in CLAUDE.md

"test is right until proven otherwise"

domain

Loaded when task keywords match

GitHub Actions rules when editing CI

manual

Never auto-loaded, deliberate lookup

Obscure platform gotchas

Invariants

These always hold. If they break, validate catches it.

Invariant

Enforced By

Every extracted section leaves a summary in CLAUDE.md

split

Every domain/manual rule exists in index.json

validate

Core rules stay inline (never extracted to file-only)

split

Frontmatter is source of truth; index.json is derived

validate

Parser only splits on ATX headings (##, ###)

parser