claude-code-handoff 1.5.1 → 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,13 +155,15 @@ 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 checks the transcript file size against a configurable threshold. When the threshold is exceeded, it **blocks** Claude's next action and forces an immediate handoff save.
+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.
 
 ```mermaid
 flowchart TD
@@ -178,18 +180,21 @@ flowchart TD
 
 ### Threshold Configuration
 
-The threshold is configured as a **percentage of the estimated maximum context** (~500KB transcript). This makes it intuitive — you think in terms of "how full is my context?" rather than raw byte counts.
+The threshold is configured as a **percentage of the 200K token context window**. The hook reads the **actual token count** from Claude's API usage data in the transcript — no guesswork, no byte-to-token estimation.
 
 | Preset | Value | Triggers at | Best for |
 |--------|-------|-------------|----------|
-| **90% (default)** | `THRESHOLD_PERCENT=90` | ~450KB | Maximizing context usage |
-| **80%** | `THRESHOLD_PERCENT=80` | ~400KB | Balance between space and safety |
-| **75%** | `THRESHOLD_PERCENT=75` | ~375KB | Short sessions, early handoff |
+| **90% (default)** | `THRESHOLD_PERCENT=90` | 180K tokens | Maximizing context usage |
+| **80%** | `THRESHOLD_PERCENT=80` | 160K tokens | Balance between space and safety |
+| **75%** | `THRESHOLD_PERCENT=75` | 150K tokens | Short sessions, early handoff |
 
-The calculation is straightforward:
+The calculation uses real data:
 ```
-MAX_CONTEXT_SIZE = 500000  (500KB — estimated max transcript)
-THRESHOLD = MAX_CONTEXT_SIZE × THRESHOLD_PERCENT / 100
+MAX_CONTEXT_TOKENS = 200000   (Claude Code's context window)
+THRESHOLD = MAX_CONTEXT_TOKENS × THRESHOLD_PERCENT / 100
+
+# The hook reads input_tokens from the last assistant message in the JSONL
+# This is the ACTUAL context size — not an estimate
 ```
 
 ### Three Ways to Configure
@@ -282,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
@@ -557,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.
@@ -572,7 +578,7 @@ A: The commands automatically summarize older sessions into a "Prior Sessions Su
 A: Absolutely. They're plain markdown. You can add notes, reorder next steps, or clean up history.
 
 **Q: How does the auto-handoff threshold work?**
-A: The threshold is a percentage of the estimated maximum transcript size (~500KB). At 90% (default), the hook triggers when the transcript reaches ~450KB. You can set any value from 1-100 via env var (`CLAUDE_CONTEXT_THRESHOLD=80`) or the `/auto-handoff` command.
+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.

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/hooks/context-monitor.sh

@@ -9,11 +9,11 @@ if [ -f "$SCRIPT_DIR/.auto-handoff-disabled" ]; then
   exit 0
 fi
 
-# Contexto máximo estimado (bytes). 500KB ~ transcript máximo típico
-MAX_CONTEXT_SIZE=500000
+# Contexto máximo do Claude Code (tokens)
+MAX_CONTEXT_TOKENS=200000
 # Threshold configurável (% do contexto). 90% padrão — maximiza uso do contexto
 THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-90}
-THRESHOLD=$((MAX_CONTEXT_SIZE * THRESHOLD_PERCENT / 100))
+THRESHOLD_TOKENS=$((MAX_CONTEXT_TOKENS * THRESHOLD_PERCENT / 100))
 
 INPUT=$(cat)
 TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty')
@@ -28,11 +28,52 @@ if [ -z "$SESSION_ID" ]; then
   exit 0
 fi
 
-# Verifica tamanho do transcript
-SIZE=$(wc -c < "$TRANSCRIPT_PATH" 2>/dev/null || echo 0)
-SIZE=$(echo "$SIZE" | tr -d ' ')
+# Extrai o input_tokens da última mensagem do assistente no JSONL.
+# Isso reflete o tamanho REAL do contexto que o Claude está usando.
+# Campos: input_tokens + cache_read_input_tokens + cache_creation_input_tokens = total input
+CURRENT_TOKENS=0
+if command -v python3 &>/dev/null; then
+  CURRENT_TOKENS=$(python3 -c "
+import json, sys
+last = 0
+with open('$TRANSCRIPT_PATH') as f:
+    for line in f:
+        try:
+            e = json.loads(line)
+            if e.get('type') == 'assistant':
+                u = e.get('message', {}).get('usage', {})
+                t = u.get('input_tokens', 0) + u.get('cache_read_input_tokens', 0) + u.get('cache_creation_input_tokens', 0)
+                if t > 0:
+                    last = t
+        except:
+            pass
+print(last)
+" 2>/dev/null)
+elif command -v node &>/dev/null; then
+  CURRENT_TOKENS=$(node -e "
+const fs = require('fs');
+const lines = fs.readFileSync('$TRANSCRIPT_PATH', 'utf-8').trim().split('\n');
+let last = 0;
+for (const line of lines) {
+  try {
+    const e = JSON.parse(line);
+    if (e.type === 'assistant' && e.message?.usage) {
+      const u = e.message.usage;
+      const t = (u.input_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0);
+      if (t > 0) last = t;
+    }
+  } catch {}
+}
+console.log(last);
+" 2>/dev/null)
+fi
+
+CURRENT_TOKENS=$(echo "$CURRENT_TOKENS" | tr -d ' \n')
+if [ -z "$CURRENT_TOKENS" ] || [ "$CURRENT_TOKENS" -eq 0 ] 2>/dev/null; then
+  exit 0
+fi
 
-if [ "$SIZE" -lt "$THRESHOLD" ]; then
+if [ "$CURRENT_TOKENS" -lt "$THRESHOLD_TOKENS" ]; then
   exit 0
 fi
 
@@ -43,10 +84,13 @@ if [ -f "$FLAG" ]; then
 fi
 touch "$FLAG"
 
+# Calcula % atual
+CURRENT_PERCENT=$((CURRENT_TOKENS * 100 / MAX_CONTEXT_TOKENS))
+
 # Bloqueia e força handoff
 cat <<HOOKEOF
 {
   "decision": "block",
-  "reason": "⚠️ AUTO-HANDOFF: O contexto atingiu ${THRESHOLD_PERCENT}% do limite. Você DEVE salvar o handoff AGORA.\n\nSiga estes passos IMEDIATAMENTE:\n1. Analise a conversa inteira e extraia: o que foi feito, próximos passos, arquivos-chave, decisões\n2. Escreva o handoff em .claude/handoffs/_active.md seguindo o template padrão\n3. Diga ao usuário: 'Handoff salvo automaticamente. Use /clear e depois /resume para continuar.'\n\nNÃO continue com outro trabalho até o handoff estar salvo."
+  "reason": "⚠️ AUTO-HANDOFF: O contexto atingiu ${CURRENT_PERCENT}% do limite (${CURRENT_TOKENS}/${MAX_CONTEXT_TOKENS} tokens). Você DEVE salvar o handoff AGORA.\n\nSiga estes passos IMEDIATAMENTE:\n1. Analise a conversa inteira e extraia: o que foi feito, próximos passos, arquivos-chave, decisões\n2. Escreva o handoff em .claude/handoffs/_active.md seguindo o template padrão\n3. Diga ao usuário: 'Handoff salvo automaticamente. Use /clear e depois /resume para continuar.'\n\nNÃO continue com outro trabalho até o handoff estar salvo."
 }
 HOOKEOF

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.5.1",
-  "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"
   },