ctxcraft

ctxcraft

Evaluate and optimize your AI agent's context. Save tokens, cut costs.

ctxcraft analyzes your .claude/ directory structure and provides actionable recommendations to reduce token consumption — without losing any functionality.

The Problem

AI coding agents (Claude Code, Cursor, Windsurf) load context files on every conversation. As your .claude/ directory grows, silent token waste accumulates:

• Verbose rule files that could be cut in half
• Duplicated content across rules, skills, and CLAUDE.md
• Unused skills/agents that are never invoked
• Always-on files that should be loaded on-demand

ctxcraft finds and fixes all of this.

Quick Start

Option 1: Plugin Marketplace (Recommended)

# Add marketplace (one-time)
claude plugin marketplace add warrenth/ctxcraft

# Install plugin (run per project)
claude plugin install ctxcraft@tools

Then in Claude Code:

/ctxcraft:evaluate    # Analyze token efficiency
/ctxcraft:optimize    # Auto-fix issues
/ctxcraft:token-guide # Best practices reference

Note: claude plugin install must be run in each project. Despite scope: user, Claude Code plugins are not truly global — you need to reinstall when switching to a new project.

{
  "extraKnownMarketplaces": {
    "ctxcraft": {
      "source": { "source": "github", "repo": "warrenth/ctxcraft" }
    }
  },
  "enabledPlugins": { "ctxcraft@tools": true }
}

Option 2: Global Install

curl -sL https://raw.githubusercontent.com/warrenth/ctxcraft/main/install.sh | bash

Then in Claude Code: /evaluate, /optimize, /token-guide

curl -sL https://raw.githubusercontent.com/warrenth/ctxcraft/main/install.sh | bash -s -- --local

ctxcraft uses only read-only tools (Read, Grep, Glob) — no permission prompts needed.

How It Works

$ /ctxcraft:evaluate

━━━ Phase 1: Token Efficiency Audit ━━━

  PASS  [ 1] CLAUDE.md size
  FAIL  [ 2] Always-on tokens         → Compress rules, save ~8,848 tokens
  FAIL  [ 3] Rules file size           → Move examples to skills/
  PASS  [ 4] Rules file count
  WARN  [ 5] Duplicate sections        → Keep in one place only
  PASS  [ 6] Progressive disclosure
  ...
  PASS  [25] Cross-reference validity

━━━ Phase 2: Report ━━━

  ┌────────────────────┬────────────┬───────┐
  │ Category           │ Tokens     │ Files │
  ├────────────────────┼────────────┼───────┤
  │ Always-on (every)  │    16,848  │   14  │
  │ On-demand (lazy)   │    53,040  │   46  │
  ├────────────────────┼────────────┼───────┤
  │ Total              │    69,888  │   60  │
  └────────────────────┴────────────┴───────┘

  💡 Potential savings: ~9,168 tokens/conversation

━━━ Summary ━━━
  Quality: 86/100 (A-)
  Cost: Comfortable (Max 5x plan)
  PASS 20  WARN 3  FAIL 2

Before / After

┌──────────────────────────────────────────────────┐
│  ctxcraft — Optimization Complete                │
│                                                  │
│              Before      After       Change      │
│  Quality     78/100  →  92/100    (+14 pts)      │
│  Grade       B+      →  A                        │
│  Always-on   16,848  →   9,200   (-7,648 tok)   │
│                                                  │
│  PASS 20 → 24   WARN 3 → 1   FAIL 2 → 0        │
└──────────────────────────────────────────────────┘

What /optimize Does

1. Compress — Shrink verbose rules and CLAUDE.md while preserving meaning
2. Deduplicate — Merge overlapping rules into a single source of truth
3. Clean up — Identify and remove unused skills/agents
4. Restructure — Move always-on content to on-demand skills
5. Split references — Extract details from large SKILL.md (>250 lines) into references/
6. Self-clean — Remove ctxcraft files after optimization

All changes require user confirmation before applying.

25 Checks

Token Efficiency (1–8)