claude-code-handoff 1.8.1 → 1.9.0

package/README.md

@@ -253,7 +253,7 @@ THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-90}   # change 90 to your value
 
 - **One-shot trigger**: A flag file in `/tmp` (per session ID) prevents infinite loops — the hook triggers exactly once per session, even if Claude's handoff response pushes the transcript further
 - **Session cleanup**: A `SessionStart` hook automatically cleans up stale flag files older than 24 hours
-- **Disable switch**: Create `.claude/hooks/.auto-handoff-disabled` to completely disable the monitor (or use `/auto-handoff` to toggle)
+- **Opt-in design**: Auto-handoff only runs when `.claude/hooks/.auto-handoff-enabled` exists (created by `/auto-handoff`). No file = disabled by default
 - **Non-destructive**: The hook only blocks and instructs — it never modifies files directly. Claude performs the actual handoff save
 
 ### What Happens When It Triggers
@@ -311,7 +311,7 @@ your-project/
     ├── hooks/
     │   ├── context-monitor.sh      ← Stop hook (monitors context size)
     │   ├── session-cleanup.sh      ← SessionStart hook (cleans old flags)
-    │   └── .auto-handoff-disabled  ← Disable flag (remove to enable)
+    │   └── .auto-handoff-enabled   ← Enable flag (created by /auto-handoff)
     ├── settings.json               ← Hook configuration
     └── handoffs/                   ← Session state (gitignored)
         ├── _active.md              ← Current workstream
@@ -604,7 +604,7 @@ A: Absolutely. They're plain markdown. You can add notes, reorder next steps, or
 A: The threshold is a percentage of Claude Code's 200K token context window. At 90% (default), the hook triggers at 180K tokens. The hook reads the **actual token count** from Claude's API usage data — not file size estimates. You can set any value from 1-100 via env var (`CLAUDE_CONTEXT_THRESHOLD=80`) or the `/auto-handoff` command.
 
 **Q: Can I disable auto-handoff?**
-A: Yes. Run `/auto-handoff` and select "Disable", or manually create the file `.claude/hooks/.auto-handoff-disabled`. Delete the file to re-enable.
+A: Yes. Run `/auto-handoff` and select "Disable", or manually delete `.claude/hooks/.auto-handoff-enabled`. Without this file, auto-handoff is off.
 
 **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.

package/cli.js

@@ -90,11 +90,12 @@ if (isReinstall) {
     console.log(`    Preserved max context: ${CYAN}${savedMaxContext} tokens${NC}`);
   }
   fs.writeFileSync(monitorPath, content);
-  // Don't touch .auto-handoff-disabled — preserve user's on/off choice
-} else {
-  // Fresh install: auto-handoff disabled by default (beta feature)
-  fs.writeFileSync(path.join(CLAUDE_DIR, 'hooks', '.auto-handoff-disabled'), '');
 }
+// Auto-handoff is opt-in: disabled by default (no file = disabled)
+// User enables via /auto-handoff which creates .auto-handoff-enabled
+// Clean up legacy disabled flag if present
+const legacyDisabled = path.join(CLAUDE_DIR, 'hooks', '.auto-handoff-disabled');
+if (fs.existsSync(legacyDisabled)) fs.unlinkSync(legacyDisabled);
 
 // 5. Configure hooks in settings.json
 console.log(`  ${YELLOW}[5/10]${NC} Configuring hooks in settings.json...`);

package/commands/auto-handoff.md

@@ -6,9 +6,9 @@ Toggle the automatic handoff context monitor on/off, configure threshold, and se
 
 ### Step 1: Check current state
 
-Check if `.claude/hooks/.auto-handoff-disabled` exists:
-- If exists → currently DISABLED
-- If not exists → currently ENABLED
+Check if `.claude/hooks/.auto-handoff-enabled` exists:
+- If exists → currently ENABLED
+- If not exists → currently DISABLED (default)
 
 Also read from `.claude/hooks/context-monitor.sh`:
 - `THRESHOLD_PERCENT` value (the default in `THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-XX}`)
@@ -30,7 +30,9 @@ Use AskUserQuestion:
 ### Step 3: Execute
 
 #### Toggle (Ativar/Desativar):
-- Create or delete `.claude/hooks/.auto-handoff-disabled`
+- Ativar: create `.claude/hooks/.auto-handoff-enabled`
+- Desativar: delete `.claude/hooks/.auto-handoff-enabled`
+- Also delete legacy `.claude/hooks/.auto-handoff-disabled` if it exists
 
 #### Ajustar threshold:
 Ask with AskUserQuestion:
@@ -52,7 +54,7 @@ Ask with AskUserQuestion:
 - Update the `MAX_CONTEXT_TOKENS` default value in `context-monitor.sh` by changing `MAX_CONTEXT_TOKENS=${CLAUDE_MAX_CONTEXT:-XXXXXX}` to the chosen value
 
 #### Ativar com configuração customizada:
-Run both "Alterar plano" and "Ajustar threshold" flows above, then delete `.claude/hooks/.auto-handoff-disabled`
+Run both "Alterar plano" and "Ajustar threshold" flows above, then create `.claude/hooks/.auto-handoff-enabled`
 
 ### Step 4: Confirm
 

package/hooks/context-monitor.sh

@@ -3,9 +3,9 @@
 # Detecta quando o contexto está próximo do limite e força o salvamento do handoff.
 # Usado como hook "Stop" do Claude Code.
 
-# Check if auto-handoff is disabled
+# Auto-handoff is opt-in: only runs if explicitly enabled
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-if [ -f "$SCRIPT_DIR/.auto-handoff-disabled" ]; then
+if [ ! -f "$SCRIPT_DIR/.auto-handoff-enabled" ]; then
   exit 0
 fi
 

package/install.sh

@@ -95,11 +95,11 @@ if [ "$IS_REINSTALL" = true ]; then
     rm -f "$CLAUDE_DIR/hooks/context-monitor.sh.bak"
     echo -e "    Preserved max context: ${CYAN}${SAVED_MAX_CONTEXT} tokens${NC}"
   fi
-  # Don't touch .auto-handoff-disabled — preserve user's on/off choice
-else
-  # Fresh install: auto-handoff disabled by default (beta feature)
-  touch "$CLAUDE_DIR/hooks/.auto-handoff-disabled"
 fi
+# Auto-handoff is opt-in: disabled by default (no file = disabled)
+# User enables via /auto-handoff which creates .auto-handoff-enabled
+# Clean up legacy disabled flag if present
+rm -f "$CLAUDE_DIR/hooks/.auto-handoff-disabled"
 
 # 5. Configure hooks in settings.json
 echo -e "  ${YELLOW}[5/10]${NC} Configuring hooks in settings.json..."

package/package.json

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

package/uninstall.sh

@@ -50,6 +50,7 @@ rm -f "$CLAUDE_DIR/rules/auto-handoff.md"
 echo -e "  ${YELLOW}[3/6]${NC} Removing hooks..."
 rm -f "$CLAUDE_DIR/hooks/context-monitor.sh"
 rm -f "$CLAUDE_DIR/hooks/session-cleanup.sh"
+rm -f "$CLAUDE_DIR/hooks/.auto-handoff-enabled"
 rm -f "$CLAUDE_DIR/hooks/.auto-handoff-disabled"
 rmdir "$CLAUDE_DIR/hooks" 2>/dev/null || true