claude-code-handoff 1.8.0 → 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

@@ -58,12 +58,44 @@ copyFile('rules/auto-handoff.md', path.join(CLAUDE_DIR, 'rules', 'auto-handoff.m
 
 // 4. Install hooks
 console.log(`  ${YELLOW}[4/10]${NC} Installing hooks...`);
-copyFile('hooks/context-monitor.sh', path.join(CLAUDE_DIR, 'hooks', 'context-monitor.sh'));
+
+// Detect reinstall: save user's custom settings before overwriting
+const monitorPath = path.join(CLAUDE_DIR, 'hooks', 'context-monitor.sh');
+let isReinstall = false;
+let savedThreshold = '';
+let savedMaxContext = '';
+if (fs.existsSync(monitorPath)) {
+  isReinstall = true;
+  const oldContent = fs.readFileSync(monitorPath, 'utf-8');
+  const thresholdMatch = oldContent.match(/CLAUDE_CONTEXT_THRESHOLD:-(\d+)/);
+  const maxContextMatch = oldContent.match(/CLAUDE_MAX_CONTEXT:-(\d+)/);
+  if (thresholdMatch) savedThreshold = thresholdMatch[1];
+  if (maxContextMatch) savedMaxContext = maxContextMatch[1];
+}
+
+copyFile('hooks/context-monitor.sh', monitorPath);
 copyFile('hooks/session-cleanup.sh', path.join(CLAUDE_DIR, 'hooks', 'session-cleanup.sh'));
-fs.chmodSync(path.join(CLAUDE_DIR, 'hooks', 'context-monitor.sh'), 0o755);
+fs.chmodSync(monitorPath, 0o755);
 fs.chmodSync(path.join(CLAUDE_DIR, 'hooks', 'session-cleanup.sh'), 0o755);
-// Auto-handoff disabled by default (beta feature)
-fs.writeFileSync(path.join(CLAUDE_DIR, 'hooks', '.auto-handoff-disabled'), '');
+
+if (isReinstall) {
+  // Restore user's custom settings
+  let content = fs.readFileSync(monitorPath, 'utf-8');
+  if (savedThreshold && savedThreshold !== '90') {
+    content = content.replace('CLAUDE_CONTEXT_THRESHOLD:-90', `CLAUDE_CONTEXT_THRESHOLD:-${savedThreshold}`);
+    console.log(`    Preserved threshold: ${CYAN}${savedThreshold}%${NC}`);
+  }
+  if (savedMaxContext && savedMaxContext !== '200000') {
+    content = content.replace('CLAUDE_MAX_CONTEXT:-200000', `CLAUDE_MAX_CONTEXT:-${savedMaxContext}`);
+    console.log(`    Preserved max context: ${CYAN}${savedMaxContext} tokens${NC}`);
+  }
+  fs.writeFileSync(monitorPath, content);
+}
+// 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

@@ -67,12 +67,39 @@ download_file "rules/auto-handoff.md" "$CLAUDE_DIR/rules/auto-handoff.md"
 
 # 4. Install hooks (auto-handoff context monitor)
 echo -e "  ${YELLOW}[4/10]${NC} Installing hooks..."
+
+# Detect reinstall: save user's custom settings before overwriting
+IS_REINSTALL=false
+SAVED_THRESHOLD=""
+SAVED_MAX_CONTEXT=""
+if [ -f "$CLAUDE_DIR/hooks/context-monitor.sh" ]; then
+  IS_REINSTALL=true
+  SAVED_THRESHOLD=$(grep -oP 'CLAUDE_CONTEXT_THRESHOLD:-\K[0-9]+' "$CLAUDE_DIR/hooks/context-monitor.sh" 2>/dev/null || echo "")
+  SAVED_MAX_CONTEXT=$(grep -oP 'CLAUDE_MAX_CONTEXT:-\K[0-9]+' "$CLAUDE_DIR/hooks/context-monitor.sh" 2>/dev/null || echo "")
+fi
+
 download_file "hooks/context-monitor.sh" "$CLAUDE_DIR/hooks/context-monitor.sh"
 download_file "hooks/session-cleanup.sh" "$CLAUDE_DIR/hooks/session-cleanup.sh"
 chmod +x "$CLAUDE_DIR/hooks/context-monitor.sh"
 chmod +x "$CLAUDE_DIR/hooks/session-cleanup.sh"
-# Auto-handoff disabled by default (beta feature)
-touch "$CLAUDE_DIR/hooks/.auto-handoff-disabled"
+
+if [ "$IS_REINSTALL" = true ]; then
+  # 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"
+    rm -f "$CLAUDE_DIR/hooks/context-monitor.sh.bak"
+    echo -e "    Preserved threshold: ${CYAN}${SAVED_THRESHOLD}%${NC}"
+  fi
+  if [ -n "$SAVED_MAX_CONTEXT" ] && [ "$SAVED_MAX_CONTEXT" != "200000" ]; then
+    sed -i.bak "s/CLAUDE_MAX_CONTEXT:-200000/CLAUDE_MAX_CONTEXT:-${SAVED_MAX_CONTEXT}/" "$CLAUDE_DIR/hooks/context-monitor.sh"
+    rm -f "$CLAUDE_DIR/hooks/context-monitor.sh.bak"
+    echo -e "    Preserved max context: ${CYAN}${SAVED_MAX_CONTEXT} tokens${NC}"
+  fi
+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.0",
+  "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
 

package/update.sh

@@ -58,14 +58,35 @@ echo -e "  ${YELLOW}[2/5]${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
+# 3. Update hooks (preserving user configuration)
 echo -e "  ${YELLOW}[3/5]${NC} Updating hooks..."
 mkdir -p "$CLAUDE_DIR/hooks"
+
+# Save user's custom settings before overwriting
+SAVED_THRESHOLD=""
+SAVED_MAX_CONTEXT=""
+if [ -f "$CLAUDE_DIR/hooks/context-monitor.sh" ]; then
+  SAVED_THRESHOLD=$(grep -oP 'CLAUDE_CONTEXT_THRESHOLD:-\K[0-9]+' "$CLAUDE_DIR/hooks/context-monitor.sh" 2>/dev/null || echo "")
+  SAVED_MAX_CONTEXT=$(grep -oP 'CLAUDE_MAX_CONTEXT:-\K[0-9]+' "$CLAUDE_DIR/hooks/context-monitor.sh" 2>/dev/null || echo "")
+fi
+
 download_file "hooks/context-monitor.sh" "$CLAUDE_DIR/hooks/context-monitor.sh"
 download_file "hooks/session-cleanup.sh" "$CLAUDE_DIR/hooks/session-cleanup.sh"
 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"
+  rm -f "$CLAUDE_DIR/hooks/context-monitor.sh.bak"
+  echo -e "    Preserved threshold: ${CYAN}${SAVED_THRESHOLD}%${NC}"
+fi
+if [ -n "$SAVED_MAX_CONTEXT" ] && [ "$SAVED_MAX_CONTEXT" != "200000" ]; then
+  sed -i.bak "s/CLAUDE_MAX_CONTEXT:-200000/CLAUDE_MAX_CONTEXT:-${SAVED_MAX_CONTEXT}/" "$CLAUDE_DIR/hooks/context-monitor.sh"
+  rm -f "$CLAUDE_DIR/hooks/context-monitor.sh.bak"
+  echo -e "    Preserved max context: ${CYAN}${SAVED_MAX_CONTEXT} tokens${NC}"
+fi
+
 # 4. Ensure hooks are configured in settings.json
 echo -e "  ${YELLOW}[4/5]${NC} Checking settings.json hooks..."
 SETTINGS_FILE="$CLAUDE_DIR/settings.json"
@@ -102,4 +123,5 @@ if [ "$CLEANED" -gt 0 ]; then
 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 ""