claude-code-handoff 1.2.1 → 1.3.1

package/README.md

@@ -10,11 +10,33 @@
 
 ## The Problem
 
-Claude Code loses all context when you `/clear` or start a new session. Long-running work gets fragmented. You waste tokens re-explaining what you were doing. Switching between features means losing track of the other one.
+Claude Code operates within a **200K token context window**. As you work, every message, tool call, file read, and response consumes tokens. Eventually, the context fills up — and that's where things break.
+
+### With auto-compact ON (default)
+
+When context usage approaches the limit, Claude Code triggers **auto-compact**: it summarizes the entire conversation into a compressed buffer of approximately **33K tokens**. In theory, this lets you keep working without interruption. In practice, the summarization is **lossy** — Claude loses critical details:
+
+- Exact file paths and line numbers discussed earlier
+- Decision rationale ("why did we choose approach A over B?")
+- Specific code patterns and variable names
+- Nuanced context about edge cases and constraints
+- What was already tried and failed
+
+The result: Claude starts repeating mistakes, asking questions you already answered, and proposing solutions that were already rejected. Development quality degrades progressively with each compaction cycle.
+
+### With auto-compact OFF
+
+If you disable auto-compact to preserve full-fidelity context, you hit a hard wall: when the 200K window fills up, you **must** `/clear`. Total context loss. You start from absolute zero — re-explaining the project, the architecture, what was done, what's next.
+
+### The real cost
+
+Either way, you lose. Auto-compact gives you a degraded Claude that forgets. Manual clear gives you an amnesiac Claude that knows nothing. Both waste tokens, time, and developer patience.
+
+**This is the problem claude-code-handoff solves.**
 
 ## The Solution
 
-**claude-code-handoff** adds 4 slash commands that give Claude persistent memory:
+Instead of relying on lossy compression or starting from zero, **claude-code-handoff** gives Claude **structured persistent memory** — 5 slash commands that capture exactly what matters and restore it cleanly:
 
 | Command | Description |
 |---------|-------------|
@@ -22,6 +44,9 @@ Claude Code loses all context when you `/clear` or start a new session. Long-run
 | `/resume` | Resume from a saved session — interactive picker |
 | `/save-handoff` | Save with options — choose where and how |
 | `/switch-context <topic>` | Switch between parallel workstreams |
+| `/delete-handoff` | Delete one or more saved handoffs |
+
+The workflow becomes: work until context is full → `/handoff` → `/clear` → `/resume` → continue with full context. No degradation, no amnesia. Just clean handoffs.
 
 Session state is stored in `.claude/handoffs/` (gitignored) — each developer keeps their own context, no conflicts.
 
@@ -34,7 +59,7 @@ cd your-project
 npx claude-code-handoff
 ```
 
-That's it. Open Claude Code and your 4 commands are ready.
+That's it. Open Claude Code and your 5 commands are ready.
 
 ---
 
@@ -133,7 +158,7 @@ graph TD
 
 ```bash
 cd your-project
-npx claude-code-handoff
+npx claude-code-handoff@1.3.0
 ```
 
 ### Option B: curl
@@ -160,7 +185,8 @@ your-project/
     │   ├── handoff.md            ← /handoff (auto-save)
     │   ├── resume.md             ← /resume (interactive picker)
     │   ├── save-handoff.md       ← /save-handoff (wizard)
-    │   └── switch-context.md     ← /switch-context (workstream switch)
+    │   ├── switch-context.md     ← /switch-context (workstream switch)
+    │   └── delete-handoff.md     ← /delete-handoff (remove handoffs)
     ├── rules/
     │   └── session-continuity.md ← Auto-loaded behavioral rules
     └── handoffs/                 ← Session state (gitignored)
@@ -327,7 +353,7 @@ The installer adds a `session-continuity.md` rules file that Claude auto-loads o
 
 - **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 4 commands natively
+- **Command awareness**: Claude understands all 5 commands natively
 
 ---
 
@@ -363,7 +389,7 @@ curl -fsSL https://raw.githubusercontent.com/eximIA-Ventures/claude-code-handoff
 ```
 
 The uninstaller:
-- Removes all 4 command files
+- Removes all 5 command files
 - Removes the rules file
 - Preserves handoff data if sessions exist (won't delete your session history)
 - Cleans `.gitignore` entries
@@ -371,7 +397,7 @@ The uninstaller:
 
 Or remove manually:
 ```bash
-rm .claude/commands/{handoff,resume,save-handoff,switch-context}.md
+rm .claude/commands/{handoff,resume,save-handoff,switch-context,delete-handoff}.md
 rm .claude/rules/session-continuity.md
 rm -rf .claude/handoffs/  # ⚠️ deletes all session history
 ```

package/cli.js

@@ -36,26 +36,27 @@ function copyFile(src, dst) {
 }
 
 // 1. Create directories
-console.log(`  ${YELLOW}[1/7]${NC} Creating directories...`);
+console.log(`  ${YELLOW}[1/8]${NC} Creating directories...`);
 ensureDir(path.join(CLAUDE_DIR, 'commands'));
 ensureDir(path.join(CLAUDE_DIR, 'rules'));
 ensureDir(path.join(CLAUDE_DIR, 'handoffs', 'archive'));
 
 // 2. Copy commands
-console.log(`  ${YELLOW}[2/7]${NC} Installing commands...`);
+console.log(`  ${YELLOW}[2/8]${NC} Installing commands...`);
 copyFile('commands/resume.md', path.join(CLAUDE_DIR, 'commands', 'resume.md'));
 copyFile('commands/save-handoff.md', path.join(CLAUDE_DIR, 'commands', 'save-handoff.md'));
 copyFile('commands/switch-context.md', path.join(CLAUDE_DIR, 'commands', 'switch-context.md'));
 copyFile('commands/handoff.md', path.join(CLAUDE_DIR, 'commands', 'handoff.md'));
+copyFile('commands/delete-handoff.md', path.join(CLAUDE_DIR, 'commands', 'delete-handoff.md'));
 
 // 3. Copy rules
-console.log(`  ${YELLOW}[3/7]${NC} Installing rules...`);
+console.log(`  ${YELLOW}[3/8]${NC} Installing rules...`);
 copyFile('rules/session-continuity.md', path.join(CLAUDE_DIR, 'rules', 'session-continuity.md'));
 
 // 4. Create initial _active.md
 const activePath = path.join(CLAUDE_DIR, 'handoffs', '_active.md');
 if (!fs.existsSync(activePath)) {
-  console.log(`  ${YELLOW}[4/7]${NC} Creating initial handoff...`);
+  console.log(`  ${YELLOW}[4/8]${NC} Creating initial handoff...`);
   fs.writeFileSync(activePath, `# Session Handoff
 
 > No active session yet. Use \`/handoff\` or \`/save-handoff\` to save your first session state.
@@ -82,11 +83,11 @@ if (!fs.existsSync(activePath)) {
 (none)
 `);
 } else {
-  console.log(`  ${YELLOW}[4/7]${NC} Handoff already exists, keeping it`);
+  console.log(`  ${YELLOW}[4/8]${NC} Handoff already exists, keeping it`);
 }
 
 // 5. Update .gitignore
-console.log(`  ${YELLOW}[5/7]${NC} Updating .gitignore...`);
+console.log(`  ${YELLOW}[5/8]${NC} Updating .gitignore...`);
 const gitignorePath = path.join(PROJECT_DIR, '.gitignore');
 if (fs.existsSync(gitignorePath)) {
   const content = fs.readFileSync(gitignorePath, 'utf-8');
@@ -98,7 +99,7 @@ if (fs.existsSync(gitignorePath)) {
 }
 
 // 6. Update CLAUDE.md
-console.log(`  ${YELLOW}[6/7]${NC} Updating CLAUDE.md...`);
+console.log(`  ${YELLOW}[6/8]${NC} Updating CLAUDE.md...`);
 const claudeMdPath = path.join(CLAUDE_DIR, 'CLAUDE.md');
 const continuityBlock = `## Session Continuity (MANDATORY)
 
@@ -123,17 +124,19 @@ if (fs.existsSync(claudeMdPath)) {
 }
 
 // 7. Verify
-console.log(`  ${YELLOW}[7/7]${NC} Verifying installation...`);
+console.log(`  ${YELLOW}[7/8]${NC} Verifying installation...`);
 let installed = 0;
-for (const f of ['resume.md', 'save-handoff.md', 'switch-context.md', 'handoff.md']) {
+for (const f of ['resume.md', 'save-handoff.md', 'switch-context.md', 'handoff.md', 'delete-handoff.md']) {
   if (fs.existsSync(path.join(CLAUDE_DIR, 'commands', f))) installed++;
 }
 
 console.log('');
-if (installed === 4) {
-  console.log(`${GREEN}  Installed successfully! (${installed}/4 commands)${NC}`);
+console.log(`  ${YELLOW}[8/8]${NC} Done!`);
+console.log('');
+if (installed === 5) {
+  console.log(`${GREEN}  Installed successfully! (${installed}/5 commands)${NC}`);
 } else {
-  console.log(`${YELLOW}  Partial install: ${installed}/4 commands${NC}`);
+  console.log(`${YELLOW}  Partial install: ${installed}/5 commands${NC}`);
 }
 console.log('');
 console.log('  Commands available:');
@@ -141,9 +144,10 @@ console.log(`    ${CYAN}/handoff${NC}              Auto-save session (no wizard)
 console.log(`    ${CYAN}/resume${NC}               Resume with wizard`);
 console.log(`    ${CYAN}/save-handoff${NC}         Save session state (wizard)`);
 console.log(`    ${CYAN}/switch-context${NC}       Switch workstream`);
+console.log(`    ${CYAN}/delete-handoff${NC}       Delete handoff(s)`);
 console.log('');
 console.log('  Files:');
-console.log('    .claude/commands/     4 command files');
+console.log('    .claude/commands/     5 command files');
 console.log('    .claude/rules/        session-continuity.md');
 console.log('    .claude/handoffs/     session state (gitignored)');
 console.log('');

package/commands/delete-handoff.md

@@ -0,0 +1,67 @@
+# Delete Handoff
+
+Delete one or more handoff files from the session continuity system.
+
+## Instructions
+
+### Step 1: Discover all handoffs
+
+1. List all `.md` files in `.claude/handoffs/` (root) and `.claude/handoffs/archive/`
+2. For each file found, read the first 10 lines to extract: **Active Workstream** and **Last Updated**
+3. Skip files that are empty or contain only the default placeholder
+
+### Step 2: Present wizard
+
+Use the AskUserQuestion tool to present available handoffs.
+
+Build the options list:
+- For each handoff found: add as option with label "[workstream name]" and description showing last updated date + file path
+- All handoffs are listed equally — no distinction between root and archive
+- If NO handoffs exist, tell the user: "No handoffs found. Nothing to delete."
+- Enable **multiSelect: true** so the user can select multiple handoffs at once
+
+Question: "Which handoff(s) do you want to delete?"
+Header: "Delete"
+
+### Step 3: Confirm deletion
+
+After the user selects, list the files that will be deleted and ask for confirmation using AskUserQuestion:
+
+Question: "Confirm deletion of [count] handoff(s)? This cannot be undone."
+Header: "Confirm"
+Options:
+- "Yes, delete" — "Permanently remove the selected handoff files"
+- "Cancel" — "Keep all handoffs, do nothing"
+
+### Step 4: Execute deletion
+
+If confirmed:
+1. Delete each selected `.md` file
+2. Report what was deleted
+
+Output:
+```
+## Handoffs deleted
+
+- [workstream name] — `[file path]`
+- [workstream name] — `[file path]`
+
+[count] handoff(s) removed.
+```
+
+If cancelled:
+```
+Deletion cancelled. No handoffs were removed.
+```
+
+## Shortcut
+
+If `$ARGUMENTS` is provided (e.g., `/delete-handoff ws2-course-creator`):
+- Search for a `.md` file matching `$ARGUMENTS` in `.claude/handoffs/` and `.claude/handoffs/archive/`
+- If found, skip to Step 3 (confirm deletion) with that single file
+- If not found, show the wizard with a note: "Handoff '$ARGUMENTS' not found. Choose from available:"
+
+## Important
+- ALWAYS confirm before deleting — never delete without explicit user approval
+- Deletion is permanent — there is no archive/trash for deleted handoffs
+- If the user selects all handoffs, warn: "This will remove ALL session handoffs."

package/commands/handoff.md

@@ -55,7 +55,7 @@ Write `.claude/handoffs/_active.md` with this template:
 > Updated automatically. Read this to resume work after /clear.
 
 ## Last Updated
-[YYYY-MM-DD] — [brief description of session]
+[YYYY-MM-DD HH:MM] — [brief description of session]
 
 ## Active Workstream
 **[workstream name]** — [one-line description]
@@ -68,7 +68,7 @@ Write `.claude/handoffs/_active.md` with this template:
 
 ## What Was Done
 
-### Session 1 ([YYYY-MM-DD])
+### Session 1 ([YYYY-MM-DD HH:MM])
 - [concrete action 1]
 - [concrete action 2]
 - ...

package/commands/resume.md

@@ -6,17 +6,17 @@ Resume work from a previous session using the handoff system.
 
 ### Step 1: Discover all handoffs
 
-1. Check if `.claude/handoffs/_active.md` exists and has content (not the default placeholder)
-2. List all `.md` files in `.claude/handoffs/archive/`
-3. For each file found, read the first 10 lines to extract: **Active Workstream**, **Last Updated**, and the first line of **What's Next**
+1. List all `.md` files in `.claude/handoffs/` (root) and `.claude/handoffs/archive/`
+2. For each file found, read the first 10 lines to extract: **Active Workstream**, **Last Updated**, and the first line of **What's Next**
+3. Skip files that are empty or contain only the default placeholder
 
 ### Step 2: Present wizard
 
 Use the AskUserQuestion tool to present available handoffs as options.
 
 Build the options list:
-- If `_active.md` has content: add it as first option with label "(active) [workstream name]" and description showing last updated date + first pending item
-- For each file in `archive/`: add as option with label "[workstream name]" and description showing last updated date + first pending item
+- For each handoff found: add as option with label "[workstream name]" and description showing last updated date + first pending item
+- All handoffs are listed equally — no "active" or "archived" distinction in the UI
 - If NO handoffs exist at all, skip the wizard and tell the user: "No handoffs found. Use `/save-handoff` at the end of this session to create the first one."
 
 Question: "Which session do you want to resume?"
@@ -64,12 +64,10 @@ Wait for user instruction before proceeding.
 ## Shortcut
 
 If `$ARGUMENTS` is provided (e.g., `/resume auth-refactor`), skip the wizard:
-- Look for `.claude/handoffs/archive/$ARGUMENTS.md` first
-- If not found, check if `_active.md` workstream slug matches `$ARGUMENTS`
+- Search for a `.md` file matching `$ARGUMENTS` in `.claude/handoffs/` and `.claude/handoffs/archive/`
 - If still not found, show the wizard with a note: "Handoff '$ARGUMENTS' not found. Choose from available:"
 
 ## Important
 - Do NOT activate any agent automatically — let the user decide
 - Do NOT start working — only present context and wait
 - If the handoff references an agent (e.g., @architect), mention it but don't activate
-- The wizard should clearly show which is the ACTIVE handoff vs archived ones

package/commands/save-handoff.md

@@ -75,7 +75,7 @@ Use this structure for the handoff content:
 > Updated automatically. Read this to resume work after /clear.
 
 ## Last Updated
-[current date and brief description]
+[YYYY-MM-DD HH:MM] — [brief description]
 
 ## Active Workstream
 [workstream name and brief context]
@@ -88,10 +88,10 @@ Use this structure for the handoff content:
 
 ## What Was Done
 
-### Session [N] ([date])
+### Session [N] ([YYYY-MM-DD HH:MM])
 [bullet points of concrete actions — be specific, not vague]
 
-### Session [N-1] ([date])
+### Session [N-1] ([YYYY-MM-DD HH:MM])
 [preserve previous sessions — don't delete history]
 
 ## What's Next

package/install.sh

@@ -45,25 +45,26 @@ download_file() {
 }
 
 # 1. Create directories
-echo -e "  ${YELLOW}[1/7]${NC} Creating directories..."
+echo -e "  ${YELLOW}[1/8]${NC} Creating directories..."
 mkdir -p "$CLAUDE_DIR/commands"
 mkdir -p "$CLAUDE_DIR/rules"
 mkdir -p "$CLAUDE_DIR/handoffs/archive"
 
 # 2. Download/copy commands
-echo -e "  ${YELLOW}[2/7]${NC} Installing commands..."
+echo -e "  ${YELLOW}[2/8]${NC} Installing commands..."
 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/handoff.md" "$CLAUDE_DIR/commands/handoff.md"
+download_file "commands/delete-handoff.md" "$CLAUDE_DIR/commands/delete-handoff.md"
 
 # 3. Download/copy rules
-echo -e "  ${YELLOW}[3/7]${NC} Installing rules..."
+echo -e "  ${YELLOW}[3/8]${NC} Installing rules..."
 download_file "rules/session-continuity.md" "$CLAUDE_DIR/rules/session-continuity.md"
 
 # 4. Create initial _active.md if not exists
 if [ ! -f "$CLAUDE_DIR/handoffs/_active.md" ]; then
-  echo -e "  ${YELLOW}[4/7]${NC} Creating initial handoff..."
+  echo -e "  ${YELLOW}[4/8]${NC} Creating initial handoff..."
   cat > "$CLAUDE_DIR/handoffs/_active.md" << 'HANDOFF'
 # Session Handoff
 
@@ -91,11 +92,11 @@ if [ ! -f "$CLAUDE_DIR/handoffs/_active.md" ]; then
 (none)
 HANDOFF
 else
-  echo -e "  ${YELLOW}[4/7]${NC} Handoff already exists, keeping it"
+  echo -e "  ${YELLOW}[4/8]${NC} Handoff already exists, keeping it"
 fi
 
 # 5. Add to .gitignore
-echo -e "  ${YELLOW}[5/7]${NC} Updating .gitignore..."
+echo -e "  ${YELLOW}[5/8]${NC} Updating .gitignore..."
 GITIGNORE="$PROJECT_DIR/.gitignore"
 if [ -f "$GITIGNORE" ]; then
   if ! grep -q ".claude/handoffs/" "$GITIGNORE" 2>/dev/null; then
@@ -109,7 +110,7 @@ else
 fi
 
 # 6. Add to CLAUDE.md
-echo -e "  ${YELLOW}[6/7]${NC} Updating CLAUDE.md..."
+echo -e "  ${YELLOW}[6/8]${NC} Updating CLAUDE.md..."
 CLAUDE_MD="$CLAUDE_DIR/CLAUDE.md"
 CONTINUITY_BLOCK='## Session Continuity (MANDATORY)
 
@@ -150,17 +151,19 @@ CLAUDEMD
 fi
 
 # 7. Summary
-echo -e "  ${YELLOW}[7/7]${NC} Verifying installation..."
+echo -e "  ${YELLOW}[7/8]${NC} Verifying installation..."
 INSTALLED=0
-for f in resume.md save-handoff.md switch-context.md handoff.md; do
+for f in resume.md save-handoff.md switch-context.md handoff.md delete-handoff.md; do
   [ -f "$CLAUDE_DIR/commands/$f" ] && INSTALLED=$((INSTALLED + 1))
 done
 
 echo ""
-if [ "$INSTALLED" -eq 4 ]; then
-  echo -e "${GREEN}  Installed successfully! ($INSTALLED/4 commands)${NC}"
+echo -e "  ${YELLOW}[8/8]${NC} Done!"
+echo ""
+if [ "$INSTALLED" -eq 5 ]; then
+  echo -e "${GREEN}  Installed successfully! ($INSTALLED/5 commands)${NC}"
 else
-  echo -e "${YELLOW}  Partial install: $INSTALLED/4 commands${NC}"
+  echo -e "${YELLOW}  Partial install: $INSTALLED/5 commands${NC}"
 fi
 echo ""
 echo -e "  Commands available:"
@@ -168,9 +171,10 @@ echo -e "    ${CYAN}/handoff${NC}              Auto-save session (no wizard)"
 echo -e "    ${CYAN}/resume${NC}               Resume with wizard"
 echo -e "    ${CYAN}/save-handoff${NC}         Save session state (wizard)"
 echo -e "    ${CYAN}/switch-context${NC}       Switch workstream"
+echo -e "    ${CYAN}/delete-handoff${NC}       Delete handoff(s)"
 echo ""
 echo -e "  Files:"
-echo -e "    .claude/commands/     4 command files"
+echo -e "    .claude/commands/     5 command files"
 echo -e "    .claude/rules/        session-continuity.md"
 echo -e "    .claude/handoffs/     session state (gitignored)"
 echo ""

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-code-handoff",
-  "version": "1.2.1",
-  "description": "Session continuity for Claude Code — 4 slash commands to save, resume, and switch workstreams across /clear",
+  "version": "1.3.1",
+  "description": "Session continuity for Claude Code — 5 slash commands to save, resume, delete, and switch workstreams across /clear",
   "bin": "./cli.js",
   "files": [
     "cli.js",

package/uninstall.sh

@@ -32,6 +32,7 @@ rm -f "$CLAUDE_DIR/commands/handoff.md"
 rm -f "$CLAUDE_DIR/commands/resume.md"
 rm -f "$CLAUDE_DIR/commands/save-handoff.md"
 rm -f "$CLAUDE_DIR/commands/switch-context.md"
+rm -f "$CLAUDE_DIR/commands/delete-handoff.md"
 # Also remove legacy Portuguese commands if present
 rm -f "$CLAUDE_DIR/commands/retomar.md"
 rm -f "$CLAUDE_DIR/commands/salvar-handoff.md"