claude-code-handoff 1.6.0 → 1.7.0

package/README.md

@@ -49,7 +49,7 @@ Instead of relying on lossy compression or starting from zero, **claude-code-han
 
 The workflow becomes: work until context is full → `/handoff` → `/clear` → `/resume` → continue with full context. No degradation, no amnesia. Just clean handoffs.
 
-**Auto-handoff** (since v1.4) monitors your context usage and **automatically triggers a handoff** when the transcript reaches a configurable threshold (default: **90%**) — so you never forget to save. Since v1.5, the threshold is configured as a **percentage of context** instead of fixed bytes, making it intuitive and portable across different setups.
+**Auto-handoff** (beta, since v1.4) monitors your context usage and **automatically triggers a handoff** when the transcript reaches a configurable threshold (default: **90%**) — so you never forget to save. Since v1.5, the threshold is configured as a **percentage of context** instead of fixed bytes. **Disabled by default** — enable it with `/auto-handoff` when you're ready to try it.
 
 Session state is stored in `.claude/handoffs/` (gitignored) — each developer keeps their own context, no conflicts.
 
@@ -62,7 +62,7 @@ cd your-project
 npx claude-code-handoff
 ```
 
-That's it. Open Claude Code and your 6 commands are ready. Auto-handoff is enabled by default at 90%.
+That's it. Open Claude Code and your 6 commands are ready. Auto-handoff is available but **disabled by default** (beta) — run `/auto-handoff` to enable it.
 
 ---
 
@@ -155,10 +155,12 @@ graph TD
 
 ---
 
-## Auto-Handoff (Context Monitor)
+## Auto-Handoff (Context Monitor) — Beta
 
 The biggest risk with handoffs is **forgetting to save**. You're deep in a task, context fills up, and everything is lost. Auto-handoff eliminates this by monitoring your transcript size and **forcing Claude to save the handoff** before it's too late.
 
+> **Note:** Auto-handoff is a beta feature and is **disabled by default**. Enable it with `/auto-handoff` inside Claude Code.
+
 ### How It Works
 
 A [Claude Code hook](https://docs.anthropic.com/en/docs/claude-code/hooks) runs after every Claude response (Stop event). It reads the **actual token count** from Claude's API usage data in the JSONL transcript and compares it against the 200K token context window. When the threshold is exceeded, it **blocks** Claude's next action and forces an immediate handoff save.
@@ -285,7 +287,8 @@ your-project/
     │   └── auto-handoff.md         ← Auto-handoff trigger rules
     ├── hooks/
     │   ├── context-monitor.sh      ← Stop hook (monitors context size)
-    │   └── session-cleanup.sh      ← SessionStart hook (cleans old flags)
+    │   ├── session-cleanup.sh      ← SessionStart hook (cleans old flags)
+    │   └── .auto-handoff-disabled  ← Disable flag (remove to enable)
     ├── settings.json               ← Hook configuration
     └── handoffs/                   ← Session state (gitignored)
         ├── _active.md              ← Current workstream
@@ -560,7 +563,7 @@ rm -rf .claude/handoffs/  # ⚠️ deletes all session history
 A: Yes. Handoff files are gitignored, so each developer has their own session state. No conflicts.
 
 **Q: What happens if I forget to `/handoff` before `/clear`?**
-A: With auto-handoff enabled (default since v1.4), Claude will automatically save the handoff when the context reaches 90%. Without it, the context is lost for that session — the previous handoff is still there, but you won't have the latest session recorded.
+A: If you've enabled auto-handoff (beta), Claude will automatically save the handoff when the context reaches the threshold. Without it, the context is lost for that session — the previous handoff is still there, but you won't have the latest session recorded.
 
 **Q: Can I have unlimited workstreams?**
 A: Yes. The `archive/` folder has no limit. Each workstream is a single `.md` file.

package/cli.js

@@ -62,6 +62,8 @@ copyFile('hooks/context-monitor.sh', path.join(CLAUDE_DIR, 'hooks', 'context-mon
 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(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'), '');
 
 // 5. Configure hooks in settings.json
 console.log(`  ${YELLOW}[5/10]${NC} Configuring hooks in settings.json...`);
@@ -177,9 +179,8 @@ console.log(`    ${CYAN}/switch-context${NC}       Switch workstream`);
 console.log(`    ${CYAN}/delete-handoff${NC}       Delete handoff(s)`);
 console.log(`    ${CYAN}/auto-handoff${NC}         Toggle auto-handoff on/off`);
 console.log('');
-console.log('  Auto-handoff:');
-console.log('    Context monitor hook installed (triggers at 90% of context)');
-console.log(`    Use ${CYAN}/auto-handoff${NC} to enable/disable or adjust threshold`);
+console.log(`  Auto-handoff: ${YELLOW}(beta — disabled by default)${NC}`);
+console.log(`    Use ${CYAN}/auto-handoff${NC} to enable and configure threshold`);
 console.log('');
 console.log('  Files:');
 console.log('    .claude/commands/     6 command files');

package/install.sh

@@ -71,6 +71,8 @@ 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"
 
 # 5. Configure hooks in settings.json
 echo -e "  ${YELLOW}[5/10]${NC} Configuring hooks in settings.json..."
@@ -306,9 +308,8 @@ echo -e "    ${CYAN}/switch-context${NC}       Switch workstream"
 echo -e "    ${CYAN}/delete-handoff${NC}       Delete handoff(s)"
 echo -e "    ${CYAN}/auto-handoff${NC}         Toggle auto-handoff on/off"
 echo ""
-echo -e "  Auto-handoff:"
-echo -e "    Context monitor hook installed (triggers at 90% of context)"
-echo -e "    Use ${CYAN}/auto-handoff${NC} to enable/disable or adjust threshold"
+echo -e "  Auto-handoff: ${YELLOW}(beta — disabled by default)${NC}"
+echo -e "    Use ${CYAN}/auto-handoff${NC} to enable and configure threshold"
 echo ""
 echo -e "  Files:"
 echo -e "    .claude/commands/     6 command files"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-code-handoff",
-  "version": "1.6.0",
-  "description": "Session continuity for Claude Code — 5 slash commands to save, resume, delete, and switch workstreams across /clear",
+  "version": "1.7.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"
   },