claude-code-handoff 2.0.1 → 2.1.0

package/README.md

@@ -36,7 +36,7 @@ Either way, you lose. Auto-compact gives you a degraded Claude that forgets. Man
 
 ## The Solution
 
-Instead of relying on lossy compression or starting from zero, **claude-code-handoff** gives Claude **structured persistent memory** — 6 slash commands that capture exactly what matters and restore it cleanly:
+Instead of relying on lossy compression or starting from zero, **claude-code-handoff** gives Claude **structured persistent memory** — 7 slash commands that capture exactly what matters and restore it cleanly:
 
 | Command | Description |
 |---------|-------------|
@@ -46,6 +46,7 @@ Instead of relying on lossy compression or starting from zero, **claude-code-han
 | `/switch-context <topic>` | Switch between parallel workstreams |
 | `/delete-handoff` | Delete one or more saved handoffs |
 | `/auto-handoff` | Enable/disable auto-handoff or adjust threshold |
+| `/context-doctor` | Diagnose context bloat and optimize token usage |
 
 The workflow becomes: work until context is full → `/handoff` → `/clear` → `/resume` → continue with full context. No degradation, no amnesia. Just clean handoffs.
 
@@ -110,8 +111,7 @@ flowchart TD
     C -->|Yes| E[Present interactive picker]
     E --> F[User selects session]
     F --> G[Load full handoff]
-    G --> H[Read key files for context]
-    H --> I[Present summary + next steps]
+    G --> I[Present summary + next steps]
     I --> J[Wait for user instruction]
 ```
 
@@ -199,8 +199,8 @@ The threshold is configured as a **percentage of your plan's context window**. T
 
 | Preset | Value | Triggers at (200K) | Triggers at (500K) | Best for |
 |--------|-------|---------------------|---------------------|----------|
-| **90% (default)** | `THRESHOLD_PERCENT=90` | 180K tokens | 450K tokens | Maximizing context usage |
-| **80%** | `THRESHOLD_PERCENT=80` | 160K tokens | 400K tokens | Balance between space and safety |
+| **90%** | `THRESHOLD_PERCENT=90` | 180K tokens | 450K tokens | Maximizing context usage |
+| **80% (default)** | `THRESHOLD_PERCENT=80` | 160K tokens | 400K tokens | Balance between space and safety |
 | **75%** | `THRESHOLD_PERCENT=75` | 150K tokens | 375K tokens | Short sessions, early handoff |
 
 The calculation uses real data:
@@ -246,7 +246,7 @@ claude: Which threshold do you want?
 ```bash
 # In .claude/hooks/context-monitor.sh, change the defaults:
 MAX_CONTEXT_TOKENS=${CLAUDE_MAX_CONTEXT:-200000}   # change 200000 to your value
-THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-90}   # change 90 to your value
+THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-80}   # change 80 to your value
 ```
 
 ### Safety Mechanisms
@@ -304,9 +304,10 @@ your-project/
     │   ├── save-handoff.md         ← /save-handoff (wizard)
     │   ├── switch-context.md       ← /switch-context (workstream switch)
     │   ├── delete-handoff.md       ← /delete-handoff (remove handoffs)
-    │   └── auto-handoff.md       ← /auto-handoff (on/off + threshold)
+    │   ├── auto-handoff.md         ← /auto-handoff (on/off + threshold)
+    │   └── context-doctor.md       ← /context-doctor (diagnose bloat)
     ├── rules/
-    │   ├── session-continuity.md   ← Auto-loaded behavioral rules
+    │   ├── session-continuity.md   ← Auto-loaded behavioral rules (lean, ~10 lines)
     │   └── auto-handoff.md         ← Auto-handoff trigger rules
     ├── hooks/
     │   ├── context-monitor.sh      ← Stop hook (monitors context size)
@@ -486,7 +487,7 @@ graph TD
         R["/resume"]
         R --> R1["Lists all sessions"]
         R --> R2["Shows summary per session"]
-        R --> R3["Loads key files"]
+        R --> R3["Lists key files (no read)"]
     end
 
     subgraph "Switch"
@@ -507,18 +508,61 @@ graph TD
 | **When** | Before `/clear` | When you need options | Start of session | Mid-session | Anytime |
 | **Interactive** | No | Yes (wizard) | Yes (picker) | No (with arg) | Yes (wizard) |
 | **Creates files** | Auto | User chooses | No | Auto | Toggle file |
-| **Reads files** | `_active.md` | `_active.md` + `archive/` | All handoffs | `_active.md` + target | Hook config |
+| **Reads files** | `_active.md` | `_active.md` + `archive/` | Handoff only (no key files) | `_active.md` + target | Hook config |
 
 ---
 
+## Context Optimization (v2.1)
+
+Every line in `CLAUDE.md` and `rules/` costs tokens on **every single message**. v2.1 aggressively minimizes the always-on footprint:
+
+| Component | v2.0 | v2.1 | Savings |
+|-----------|------|------|---------|
+| `session-continuity.md` (rule) | 28 lines | 10 lines | -64% |
+| CLAUDE.md section | 5 lines + auto-read | 2 lines, no auto-read | -60% |
+| `/resume` Key File read | 50 lines | 0 (removed) | -100% |
+| Handoff compaction | 200 line limit | 100 line limit, auto-compact | -50% |
+
+**Estimated savings: ~5-6K tokens per message** for projects with moderate CLAUDE.md and rules.
+
+### `/context-doctor` — Diagnose context bloat
+
+Run `/context-doctor` to get a full audit of your context usage:
+
+```
+you:    /context-doctor
+claude: ## Context Health Report
+
+        ### Always-on context (loaded every message)
+        | Source         | Lines | Est. tokens | Status  |
+        |----------------|-------|-------------|---------|
+        | CLAUDE.md      | 260   | ~3900       | BLOATED |
+        | rules/mcp.md   | 176   | ~2640       | BLOATED |
+        | rules/cont.md  | 10    | ~150        | OK      |
+        | **Total**      | **446** | **~6690** | —       |
+
+        ### Recommendations
+        1. Move rules/mcp.md to commands/ (saves ~2640 tokens/message)
+        2. Trim CLAUDE.md: remove code examples on lines 117-145
+        3. Compact handoff: 8 sessions → keep last 3
+
+        Want me to apply any of these optimizations?
+```
+
+### Tips for users
+
+1. **Move reference docs from `rules/` to `commands/`** — Rules are loaded every message. Commands are loaded only when invoked. If a rules file has >50 lines and is mostly reference material, move it to `commands/`.
+2. **Keep CLAUDE.md lean** — Remove generic instructions ("write clean code", error handling patterns, debugging tips). Claude already knows these. Only keep project-specific rules and guardrails.
+3. **Run `/context-doctor` after installing new tools** — MCP rules, agent definitions, and framework configs can bloat context silently.
+
 ## Behavioral Rules
 
-The installer adds a `session-continuity.md` rules file that Claude auto-loads on every session. This gives Claude awareness of the handoff system without you needing to explain it:
+The installer adds a lean `session-continuity.md` rules file (~10 lines) that Claude auto-loads on every session:
 
 - **On session start**: Claude knows `_active.md` exists but doesn't read it unless asked
 - **During work**: Claude proactively reminds you to save after significant milestones
-- **Command awareness**: Claude understands all 6 commands natively
-- **Auto-handoff awareness**: When the context monitor triggers, Claude knows exactly what to do — save the handoff immediately without asking
+- **Command awareness**: Claude understands all 7 commands natively
+- **Auto-handoff awareness**: When the context monitor triggers, Claude saves the handoff immediately
 
 ---
 
@@ -555,7 +599,7 @@ curl -fsSL https://raw.githubusercontent.com/eximIA-Ventures/claude-code-handoff
 ```
 
 The uninstaller:
-- Removes all 6 command files (including legacy `auto-handoff-toggle.md`)
+- Removes all 7 command files (including legacy `auto-handoff-toggle.md`)
 - Removes rules and hooks
 - Cleans hooks from `settings.json` (requires `jq`)
 - Preserves handoff data if sessions exist (won't delete your session history)
@@ -609,6 +653,12 @@ A: Yes. Run `/auto-handoff` and select "Disable", or manually delete `.claude/ho
 **Q: What if auto-handoff triggers too early/late?**
 A: Adjust the threshold. If it triggers too early, increase to 95%. If you're running out of context before it triggers, lower to 80% or 75%. Use `/auto-handoff` to change it interactively.
 
+**Q: My context fills up too fast. What can I do?**
+A: Run `/context-doctor` to audit your always-on context (CLAUDE.md + rules/). Common fixes: move large rules files to commands/ (on-demand loading), trim generic boilerplate from CLAUDE.md, and compact old handoff sessions. See the [Context Optimization](#context-optimization-v21) section.
+
+**Q: What changed in v2.1?**
+A: v2.1 focuses on context efficiency: leaner rules file (28→10 lines), no auto-read on session start (saves double reading), `/resume` no longer reads Key Files by default (saves ~50 lines), handoff compaction at 3 sessions (100 line target), and new `/context-doctor` diagnostic command.
+
 ---
 
 ## Contributing

package/cli.js

@@ -26,7 +26,7 @@ const SCRIPT_DIR = __dirname;
 // ─── Banner ───────────────────────────────────────────
 console.log('');
 console.log(`  ${AMBER}${BOLD}┌──────────────────────────────────────┐${NC}`);
-console.log(`  ${AMBER}${BOLD}│${NC}   ${WHITE}${BOLD}claude-code-handoff${NC}  ${DIM}v1.9${NC}        ${AMBER}${BOLD}│${NC}`);
+console.log(`  ${AMBER}${BOLD}│${NC}   ${WHITE}${BOLD}claude-code-handoff${NC}  ${DIM}v2.1${NC}        ${AMBER}${BOLD}│${NC}`);
 console.log(`  ${AMBER}${BOLD}│${NC}   ${GRAY}Session Continuity for Claude Code${NC}  ${AMBER}${BOLD}│${NC}`);
 console.log(`  ${AMBER}${BOLD}└──────────────────────────────────────┘${NC}`);
 console.log('');
@@ -86,7 +86,8 @@ copyFile('commands/switch-context.md', path.join(CLAUDE_DIR, 'commands', 'switch
 copyFile('commands/handoff.md', path.join(CLAUDE_DIR, 'commands', 'handoff.md'));
 copyFile('commands/delete-handoff.md', path.join(CLAUDE_DIR, 'commands', 'delete-handoff.md'));
 copyFile('commands/auto-handoff.md', path.join(CLAUDE_DIR, 'commands', 'auto-handoff.md'));
-ok('6 slash commands installed');
+copyFile('commands/context-doctor.md', path.join(CLAUDE_DIR, 'commands', 'context-doctor.md'));
+ok('7 slash commands installed');
 
 // ─── Rules ────────────────────────────────────────────
 head('Installing rules');
@@ -199,11 +200,9 @@ if (fs.existsSync(gitignorePath)) {
 head('Updating CLAUDE.md');
 
 const claudeMdPath = path.join(CLAUDE_DIR, 'CLAUDE.md');
-const continuityBlock = `## Session Continuity (MANDATORY)
+const continuityBlock = `## Session Continuity
 
-At the START of every session, read \`.claude/handoffs/_active.md\` to recover context from prior sessions.
-During work, update the handoff proactively after significant milestones.
-Use \`/handoff\` before \`/clear\`. Use \`/resume\` to pick up. Use \`/switch-context <topic>\` to switch workstreams.`;
+Use \`/resume\` to pick up from a previous session. Use \`/handoff\` before \`/clear\` to save.`;
 
 if (fs.existsSync(claudeMdPath)) {
   const content = fs.readFileSync(claudeMdPath, 'utf-8');
@@ -237,17 +236,17 @@ if (cleaned > 0) info(`Removed ${cleaned} legacy command(s)`);
 head('Verifying');
 
 let installed = 0;
-for (const f of ['resume.md', 'save-handoff.md', 'switch-context.md', 'handoff.md', 'delete-handoff.md', 'auto-handoff.md']) {
+for (const f of ['resume.md', 'save-handoff.md', 'switch-context.md', 'handoff.md', 'delete-handoff.md', 'auto-handoff.md', 'context-doctor.md']) {
   if (fs.existsSync(path.join(CLAUDE_DIR, 'commands', f))) installed++;
 }
 let hooksOk = 0;
 if (fs.existsSync(path.join(CLAUDE_DIR, 'hooks', 'context-monitor.sh'))) hooksOk++;
 if (fs.existsSync(path.join(CLAUDE_DIR, 'hooks', 'session-cleanup.sh'))) hooksOk++;
 
-if (installed === 6 && hooksOk === 2) {
-  ok(`${installed}/6 commands, ${hooksOk}/2 hooks`);
+if (installed === 7 && hooksOk === 2) {
+  ok(`${installed}/7 commands, ${hooksOk}/2 hooks`);
 } else {
-  fail(`Partial: ${installed}/6 commands, ${hooksOk}/2 hooks`);
+  fail(`Partial: ${installed}/7 commands, ${hooksOk}/2 hooks`);
 }
 
 // ─── Done ─────────────────────────────────────────────
@@ -263,6 +262,7 @@ console.log(`    ${CYAN}/save-handoff${NC}       ${GRAY}Save with options${NC}`)
 console.log(`    ${CYAN}/switch-context${NC}     ${GRAY}Switch workstream${NC}`);
 console.log(`    ${CYAN}/delete-handoff${NC}     ${GRAY}Delete handoff(s)${NC}`);
 console.log(`    ${CYAN}/auto-handoff${NC}       ${GRAY}Toggle auto-handoff${NC}`);
+console.log(`    ${CYAN}/context-doctor${NC}     ${GRAY}Diagnose context bloat${NC}`);
 console.log('');
 console.log(`  ${WHITE}${BOLD}Auto-handoff:${NC} ${DIM}beta — disabled by default${NC}`);
 console.log(`  ${GRAY}Run ${CYAN}/auto-handoff${GRAY} inside Claude Code to enable${NC}`);

package/commands/context-doctor.md

@@ -0,0 +1,96 @@
+# Context Doctor
+
+Diagnose context usage and recommend optimizations to maximize your usable context window.
+
+## Instructions
+
+### Step 1: Audit always-loaded files
+
+These files are loaded into Claude's context on **every single message**:
+
+1. **CLAUDE.md**: Read `.claude/CLAUDE.md` and count lines
+2. **Rules**: List all `.md` files in `.claude/rules/` — for each, count lines and note the filename
+3. **Global CLAUDE.md**: Check if the project has a parent CLAUDE.md (from `~/.claude/CLAUDE.md`) — note if it exists
+
+Calculate total "always-on" lines (CLAUDE.md + all rules).
+
+### Step 2: Audit handoff size
+
+1. Read `.claude/handoffs/_active.md` and count lines
+2. Count session entries (### Session N patterns)
+3. Check if compaction is needed (>3 sessions or >100 lines)
+
+### Step 3: Scan for bloat patterns
+
+Check CLAUDE.md for common bloat patterns:
+- Code examples (```...```) — these consume many tokens for little value
+- Generic rules that Claude already knows (error handling patterns, "write clean code", "follow best practices")
+- Duplicate instructions (same info in CLAUDE.md AND rules/)
+- Environment setup / debugging tips
+- Long lists of "NEVER do X" (>10 items)
+
+Check rules/ for:
+- Files >50 lines (likely too verbose)
+- Content that could be a command/skill instead (loaded on-demand)
+
+### Step 4: Present report
+
+```
+## Context Health Report
+
+### Always-on context (loaded every message)
+| Source | Lines | Est. tokens | Status |
+|--------|-------|-------------|--------|
+| CLAUDE.md | X | ~Y | [OK/BLOATED] |
+| rules/file1.md | X | ~Y | [OK/BLOATED] |
+| rules/file2.md | X | ~Y | [OK/BLOATED] |
+| **Total** | **X** | **~Y** | — |
+
+### Handoff state
+- Active handoff: X lines, N sessions
+- [NEEDS COMPACTION / OK]
+
+### Recommendations
+[numbered list of specific, actionable recommendations]
+```
+
+### Token estimation
+Use this rough formula: `tokens ≈ lines × 15` (average for markdown with code).
+
+### Recommendation templates
+
+Use these as appropriate:
+
+1. **"Move rules/X.md to commands/"** — When a rules file is >50 lines and contains reference material (not behavioral rules). Moving to commands/ makes it a skill that's only loaded when invoked.
+   - Action: `mv .claude/rules/X.md .claude/commands/X.md` and remove the `paths:` frontmatter
+
+2. **"Trim CLAUDE.md"** — When CLAUDE.md has code examples, generic best practices, or debug tips.
+   - Action: Remove generic content. Keep only project-specific rules and critical guardrails.
+
+3. **"Compact handoff"** — When handoff has >3 sessions or >100 lines.
+   - Action: Run `/handoff` which will auto-compact, or manually edit `_active.md`.
+
+4. **"Split rules file"** — When a rules file has both behavioral rules AND reference docs.
+   - Action: Keep behavioral rules (short, <20 lines) in rules/. Move reference docs to commands/.
+
+5. **"Remove duplicate instructions"** — When the same info appears in CLAUDE.md and rules/.
+   - Action: Keep in one place only.
+
+### Step 5: Offer to fix
+
+After presenting the report, ask:
+
+Question: "Want me to apply any of these optimizations?"
+Header: "Fix"
+Options:
+- "Apply all recommendations" — "Automatically fix all issues found"
+- "Let me choose" — "I'll tell you which ones to apply"
+- "Just the report" — "No changes, I'll handle it manually"
+
+If the user chooses "Apply all" or specific fixes, execute them.
+
+## Important
+- This is a READ-ONLY diagnostic by default — only modify files if the user explicitly approves
+- Be specific in recommendations — "Remove lines 45-80 from CLAUDE.md (code examples)" not "trim CLAUDE.md"
+- Show before/after line counts when making changes
+- Never remove content from rules/ without explaining what it does and confirming

package/commands/handoff.md

@@ -109,10 +109,25 @@ This command exists because:
 2. **Context-aware** — it appends to the active handoff if the workstream matches, or creates a new one if it doesn't.
 3. **Pre-clear workflow** — the natural flow is: work → `/handoff` → `/clear` → `/resume`.
 
+## Compaction Rule
+
+When a handoff exceeds 3 session entries in "What Was Done":
+1. Keep the **last 3 sessions** in full detail
+2. Merge all older sessions into a single **"Prior Sessions Summary (1-N)"** section with 1-2 bullet points each
+3. Example:
+```markdown
+### Prior Sessions Summary (1-5)
+- Sessions 1-2: Initial setup, D1-D4 decided
+- Session 3: Refactored auth module
+- Sessions 4-5: API integration, E2E tests added
+```
+4. Target: keep the entire handoff under **100 lines**
+5. The Decisions Registry is NEVER compacted — all decisions are preserved
+
 ## Important
 - Be THOROUGH — extract everything relevant from the conversation
 - Be PRECISE — file paths, specific changes, exact error messages
 - Be ACTIONABLE — next steps should be specific enough to execute cold
 - NEVER delete existing handoff data — always append or archive
-- Keep under 200 lines — summarize older sessions if handoff grows large
+- Keep under 100 lines — compact older sessions aggressively
 - If conversation is very short or trivial, still save (even a one-liner is better than nothing)

package/commands/resume.md

@@ -27,23 +27,18 @@ Header: "Handoff"
 Once the user selects, read the full handoff file and extract:
 - Active Workstream
 - Active Agent(s)
-- What Was Done (last session summary)
+- What Was Done (last session summary only)
 - What's Next (pending items)
-- Key Files
+- Key Files (list only — do NOT read the files)
 - Decisions Registry (if any)
 
-### Step 4: Refresh context
-
-If **Key Files** lists a main document (Current Document field), read the first 50 lines of it.
-
-### Step 5: Present context
+### Step 4: Present context
 
 ```
 ## Resuming session
 
 **Workstream:** [name]
 **Agent(s):** [active agents]
-**Document:** [main file]
 **Last updated:** [date]
 
 ### Last session summary
@@ -57,7 +52,7 @@ If **Key Files** lists a main document (Current Document field), read the first
 What would you like to do?
 ```
 
-### Step 6: Wait
+### Step 5: Wait
 
 Wait for user instruction before proceeding.
 
@@ -70,4 +65,5 @@ If `$ARGUMENTS` is provided (e.g., `/resume auth-refactor`), skip the wizard:
 ## Important
 - Do NOT activate any agent automatically — let the user decide
 - Do NOT start working — only present context and wait
+- Do NOT read Key Files — just list them. The user can ask to read specific files when needed
 - If the handoff references an agent (e.g., @architect), mention it but don't activate

package/commands/save-handoff.md

@@ -125,11 +125,18 @@ If `$ARGUMENTS` is provided:
 - If it matches an existing archive name: update that specific archive file directly (skip wizard)
 - Otherwise: treat as the name for a new context (skip wizard, go to "Save as new context" flow)
 
+## Compaction Rule
+
+When a handoff exceeds 3 session entries in "What Was Done":
+1. Keep the **last 3 sessions** in full detail
+2. Merge all older sessions into a single **"Prior Sessions Summary (1-N)"** section with 1-2 bullet points each
+3. Target: keep the entire handoff under **100 lines**
+4. The Decisions Registry is NEVER compacted — all decisions are preserved
+
 ## Important
 - NEVER delete or overwrite without archiving first — always move to archive/
-- PRESERVE session history — append, don't replace
+- PRESERVE session history — append, don't replace (but compact older sessions)
 - Be PRECISE — file paths, decision IDs, specific changes
 - Be ACTIONABLE — someone reading cold should know exactly what to do
-- Keep CONCISE — target <200 lines per handoff
-- If a handoff exceeds 300 lines, summarize older sessions into "Prior Sessions Summary"
+- Keep CONCISE — target <100 lines per handoff
 - Slug derivation: lowercase, trim, replace spaces/special chars with hyphens, max 40 chars

package/install.sh

@@ -31,7 +31,7 @@ head() { echo -e "\n  ${AMBER}${BOLD}$1${RESET}"; }
 # ─── Banner ───────────────────────────────────────────
 echo ""
 echo -e "  ${AMBER}${BOLD}┌──────────────────────────────────────┐${RESET}"
-echo -e "  ${AMBER}${BOLD}│${RESET}   ${WHITE}${BOLD}claude-code-handoff${RESET}  ${DIM}v1.9${RESET}        ${AMBER}${BOLD}│${RESET}"
+echo -e "  ${AMBER}${BOLD}│${RESET}   ${WHITE}${BOLD}claude-code-handoff${RESET}  ${DIM}v2.1${RESET}        ${AMBER}${BOLD}│${RESET}"
 echo -e "  ${AMBER}${BOLD}│${RESET}   ${GRAY}Session Continuity for Claude Code${RESET}  ${AMBER}${BOLD}│${RESET}"
 echo -e "  ${AMBER}${BOLD}└──────────────────────────────────────┘${RESET}"
 echo ""
@@ -87,7 +87,8 @@ download_file "commands/switch-context.md" "$CLAUDE_DIR/commands/switch-context.
 download_file "commands/handoff.md" "$CLAUDE_DIR/commands/handoff.md"
 download_file "commands/delete-handoff.md" "$CLAUDE_DIR/commands/delete-handoff.md"
 download_file "commands/auto-handoff.md" "$CLAUDE_DIR/commands/auto-handoff.md"
-ok "6 slash commands installed"
+download_file "commands/context-doctor.md" "$CLAUDE_DIR/commands/context-doctor.md"
+ok "7 slash commands installed"
 
 # ─── Rules ────────────────────────────────────────────
 head "Installing rules"
@@ -303,11 +304,9 @@ if [ -f "$CLAUDE_MD" ]; then
       /^# / && !done {
         print
         print ""
-        print "## Session Continuity (MANDATORY)"
+        print "## Session Continuity"
         print ""
-        print "At the START of every session, read `.claude/handoffs/_active.md` to recover context from prior sessions."
-        print "During work, update the handoff proactively after significant milestones."
-        print "Use `/handoff` before `/clear`. Use `/resume` to pick up. Use `/switch-context <topic>` to switch workstreams."
+        print "Use `/resume` to pick up from a previous session. Use `/handoff` before `/clear` to save."
         print ""
         done=1
         next
@@ -323,11 +322,9 @@ else
   cat > "$CLAUDE_MD" << 'CLAUDEMD'
 # Project Rules
 
-## Session Continuity (MANDATORY)
+## Session Continuity
 
-At the START of every session, read `.claude/handoffs/_active.md` to recover context from prior sessions.
-During work, update the handoff proactively after significant milestones.
-Use `/handoff` before `/clear`. Use `/resume` to pick up. Use `/switch-context <topic>` to switch workstreams.
+Use `/resume` to pick up from a previous session. Use `/handoff` before `/clear` to save.
 CLAUDEMD
   ok "CLAUDE.md created"
 fi
@@ -348,17 +345,17 @@ fi
 head "Verifying"
 
 INSTALLED=0
-for f in resume.md save-handoff.md switch-context.md handoff.md delete-handoff.md auto-handoff.md; do
+for f in resume.md save-handoff.md switch-context.md handoff.md delete-handoff.md auto-handoff.md context-doctor.md; do
   [ -f "$CLAUDE_DIR/commands/$f" ] && INSTALLED=$((INSTALLED + 1))
 done
 HOOKS_OK=0
 [ -f "$CLAUDE_DIR/hooks/context-monitor.sh" ] && HOOKS_OK=$((HOOKS_OK + 1))
 [ -f "$CLAUDE_DIR/hooks/session-cleanup.sh" ] && HOOKS_OK=$((HOOKS_OK + 1))
 
-if [ "$INSTALLED" -eq 6 ] && [ "$HOOKS_OK" -eq 2 ]; then
-  ok "${INSTALLED}/6 commands, ${HOOKS_OK}/2 hooks"
+if [ "$INSTALLED" -eq 7 ] && [ "$HOOKS_OK" -eq 2 ]; then
+  ok "${INSTALLED}/7 commands, ${HOOKS_OK}/2 hooks"
 else
-  fail "Partial: ${INSTALLED}/6 commands, ${HOOKS_OK}/2 hooks"
+  fail "Partial: ${INSTALLED}/7 commands, ${HOOKS_OK}/2 hooks"
 fi
 
 # ─── Done ─────────────────────────────────────────────
@@ -374,6 +371,7 @@ echo -e "    ${CYAN}/save-handoff${RESET}       ${GRAY}Save with options${RESET}
 echo -e "    ${CYAN}/switch-context${RESET}     ${GRAY}Switch workstream${RESET}"
 echo -e "    ${CYAN}/delete-handoff${RESET}     ${GRAY}Delete handoff(s)${RESET}"
 echo -e "    ${CYAN}/auto-handoff${RESET}       ${GRAY}Toggle auto-handoff${RESET}"
+echo -e "    ${CYAN}/context-doctor${RESET}     ${GRAY}Diagnose context bloat${RESET}"
 echo ""
 echo -e "  ${WHITE}${BOLD}Auto-handoff:${RESET} ${DIM}beta — disabled by default${RESET}"
 echo -e "  ${GRAY}Run ${CYAN}/auto-handoff${GRAY} inside Claude Code to enable${RESET}"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-code-handoff",
-  "version": "2.0.1",
-  "description": "Session continuity for Claude Code — 6 slash commands to save, resume, delete, and switch workstreams across /clear",
+  "version": "2.1.0",
+  "description": "Session continuity for Claude Code — 7 slash commands to save, resume, diagnose, and switch workstreams across /clear",
   "bin": {
     "claude-code-handoff": "./cli.js"
   },

package/rules/session-continuity.md

@@ -2,26 +2,10 @@
 paths: **/*
 ---
 
-# Session Continuity Rules
+# Session Continuity
 
-## Handoff System
+This project uses `.claude/handoffs/` for session continuity across `/clear`.
 
-This project uses a handoff system for session continuity. Handoff files are stored in `.claude/handoffs/`.
-
-### On Session Start
-- If `.claude/handoffs/_active.md` exists and has content, be aware of it but do NOT read it automatically unless the user invokes `/resume` or says "continue"/"resume"
-
-### During Work
-- After completing significant milestones (major edits, decisions made, features implemented), proactively update the handoff by writing to `.claude/handoffs/_active.md`
-- If the session has been going for a while and substantial work was done, remind the user: "Want me to save the handoff before continuing?"
-
-### Handoff Structure
-- `_active.md` — current active workstream (the ONE thing being worked on now)
-- `archive/` — paused or completed workstreams (switched via `/switch-context`)
-
-### Commands Available
-- `/resume` — resume from active handoff (interactive wizard)
-- `/resume <topic>` — resume from a specific archived handoff
-- `/save-handoff` — save current state (interactive wizard)
-- `/switch-context <topic>` — switch workstream (archives current, loads target)
-- `/handoff` — auto-save session state (no wizard, just save and go)
+- Do NOT read `_active.md` automatically — wait for `/resume` or user saying "continue"/"resume"
+- After significant milestones, remind: "Want me to save the handoff?"
+- Commands: `/resume`, `/handoff`, `/save-handoff`, `/switch-context`, `/delete-handoff`, `/auto-handoff`

package/uninstall.sh

@@ -34,6 +34,7 @@ rm -f "$CLAUDE_DIR/commands/save-handoff.md"
 rm -f "$CLAUDE_DIR/commands/switch-context.md"
 rm -f "$CLAUDE_DIR/commands/delete-handoff.md"
 rm -f "$CLAUDE_DIR/commands/auto-handoff.md"
+rm -f "$CLAUDE_DIR/commands/context-doctor.md"
 # Also remove legacy commands if present
 rm -f "$CLAUDE_DIR/commands/auto-handoff-toggle.md"
 # Also remove legacy Portuguese commands if present

package/update.sh

@@ -18,7 +18,7 @@ CLAUDE_DIR="$PROJECT_DIR/.claude"
 
 echo ""
 echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-echo -e "${CYAN}  claude-code-handoff — Update${NC}"
+echo -e "${CYAN}  claude-code-handoff — Update v2.1${NC}"
 echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
 echo ""
 echo -e "  Project: ${GREEN}$PROJECT_DIR${NC}"
@@ -45,21 +45,22 @@ download_file() {
 }
 
 # 1. Update commands
-echo -e "  ${YELLOW}[1/5]${NC} Updating commands..."
+echo -e "  ${YELLOW}[1/6]${NC} Updating commands..."
 download_file "commands/handoff.md" "$CLAUDE_DIR/commands/handoff.md"
 download_file "commands/resume.md" "$CLAUDE_DIR/commands/resume.md"
 download_file "commands/save-handoff.md" "$CLAUDE_DIR/commands/save-handoff.md"
 download_file "commands/switch-context.md" "$CLAUDE_DIR/commands/switch-context.md"
 download_file "commands/delete-handoff.md" "$CLAUDE_DIR/commands/delete-handoff.md"
 download_file "commands/auto-handoff.md" "$CLAUDE_DIR/commands/auto-handoff.md"
+download_file "commands/context-doctor.md" "$CLAUDE_DIR/commands/context-doctor.md"
 
 # 2. Update rules
-echo -e "  ${YELLOW}[2/5]${NC} Updating rules..."
+echo -e "  ${YELLOW}[2/6]${NC} Updating rules..."
 download_file "rules/session-continuity.md" "$CLAUDE_DIR/rules/session-continuity.md"
 download_file "rules/auto-handoff.md" "$CLAUDE_DIR/rules/auto-handoff.md"
 
 # 3. Update hooks (preserving user configuration)
-echo -e "  ${YELLOW}[3/5]${NC} Updating hooks..."
+echo -e "  ${YELLOW}[3/6]${NC} Updating hooks..."
 mkdir -p "$CLAUDE_DIR/hooks"
 
 # Save user's custom settings before overwriting
@@ -76,8 +77,8 @@ chmod +x "$CLAUDE_DIR/hooks/context-monitor.sh"
 chmod +x "$CLAUDE_DIR/hooks/session-cleanup.sh"
 
 # Restore user's custom settings
-if [ -n "$SAVED_THRESHOLD" ] && [ "$SAVED_THRESHOLD" != "90" ]; then
-  sed -i.bak "s/CLAUDE_CONTEXT_THRESHOLD:-90/CLAUDE_CONTEXT_THRESHOLD:-${SAVED_THRESHOLD}/" "$CLAUDE_DIR/hooks/context-monitor.sh"
+if [ -n "$SAVED_THRESHOLD" ] && [ "$SAVED_THRESHOLD" != "80" ]; then
+  sed -i.bak "s/CLAUDE_CONTEXT_THRESHOLD:-80/CLAUDE_CONTEXT_THRESHOLD:-${SAVED_THRESHOLD}/" "$CLAUDE_DIR/hooks/context-monitor.sh"
   rm -f "$CLAUDE_DIR/hooks/context-monitor.sh.bak"
   echo -e "    Preserved threshold: ${CYAN}${SAVED_THRESHOLD}%${NC}"
 fi
@@ -88,7 +89,7 @@ if [ -n "$SAVED_MAX_CONTEXT" ] && [ "$SAVED_MAX_CONTEXT" != "200000" ]; then
 fi
 
 # 4. Ensure hooks are configured in settings.json
-echo -e "  ${YELLOW}[4/5]${NC} Checking settings.json hooks..."
+echo -e "  ${YELLOW}[4/6]${NC} Checking settings.json hooks..."
 SETTINGS_FILE="$CLAUDE_DIR/settings.json"
 if [ -f "$SETTINGS_FILE" ]; then
   if ! grep -q "context-monitor" "$SETTINGS_FILE" 2>/dev/null; then
@@ -106,8 +107,38 @@ else
   echo -e "    ${YELLOW}⚠ settings.json not found — run install first${NC}"
 fi
 
-# 5. Remove legacy files if present
-echo -e "  ${YELLOW}[5/5]${NC} Cleaning up legacy files..."
+# 5. Migrate CLAUDE.md (v2.1: remove mandatory read, slim down)
+echo -e "  ${YELLOW}[5/6]${NC} Migrating CLAUDE.md..."
+CLAUDE_MD="$CLAUDE_DIR/CLAUDE.md"
+MIGRATED=false
+if [ -f "$CLAUDE_MD" ]; then
+  # Replace old verbose section with lean version
+  if grep -q "At the START of every session, read" "$CLAUDE_MD" 2>/dev/null; then
+    TEMP_FILE=$(mktemp)
+    awk '
+      /## Session Continuity/ {
+        print "## Session Continuity"
+        print ""
+        print "Use `/resume` to pick up from a previous session. Use `/handoff` before `/clear` to save."
+        skip=1
+        next
+      }
+      skip && /^## / && !/Session Continuity/ {
+        skip=0
+      }
+      skip { next }
+      { print }
+    ' "$CLAUDE_MD" > "$TEMP_FILE"
+    mv "$TEMP_FILE" "$CLAUDE_MD"
+    MIGRATED=true
+    echo -e "    ${GREEN}Migrated: removed auto-read rule (saves ~3K tokens/message)${NC}"
+  else
+    echo -e "    Already up to date"
+  fi
+fi
+
+# 6. Remove legacy files if present
+echo -e "  ${YELLOW}[6/6]${NC} Cleaning up legacy files..."
 CLEANED=0
 for f in retomar.md salvar-handoff.md trocar-contexto.md auto-handoff-toggle.md; do
   if [ -f "$CLAUDE_DIR/commands/$f" ]; then
@@ -121,7 +152,11 @@ echo -e "${GREEN}  Updated successfully!${NC}"
 if [ "$CLEANED" -gt 0 ]; then
   echo -e "  Removed $CLEANED legacy command(s)"
 fi
+if [ "$MIGRATED" = true ]; then
+  echo -e "  ${CYAN}CLAUDE.md migrated to lean format (context optimization)${NC}"
+fi
 echo ""
 echo -e "  Handoff data in .claude/handoffs/ was ${CYAN}not touched${NC}."
 echo -e "  Auto-handoff settings (threshold, plan, on/off) were ${CYAN}preserved${NC}."
+echo -e "  ${CYAN}New:${NC} /context-doctor — diagnose context bloat"
 echo ""