claude-code-handoff 1.5.0 → 1.6.0

package/README.md

@@ -36,7 +36,7 @@ Either way, you lose. Auto-compact gives you a degraded Claude that forgets. Man
 
 ## The Solution
 
-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:
+Instead of relying on lossy compression or starting from zero, **claude-code-handoff** gives Claude **structured persistent memory** — 6 slash commands that capture exactly what matters and restore it cleanly:
 
 | Command | Description |
 |---------|-------------|
@@ -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.
 
-**New in v1.4:** Auto-handoff monitors your context usage and **automatically triggers a handoff** when the transcript reaches 90% capacity — so you never forget to save.
+**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.
 
 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 5 commands are ready.
+That's it. Open Claude Code and your 6 commands are ready. Auto-handoff is enabled by default at 90%.
 
 ---
 
@@ -157,38 +157,91 @@ graph TD
 
 ## Auto-Handoff (Context Monitor)
 
-The biggest risk with handoffs is **forgetting to save**. Auto-handoff eliminates this by monitoring your transcript size and forcing a save when context is running low.
+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.
 
 ### 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.
+
 ```mermaid
 flowchart TD
     A[Claude responds] --> B[Stop hook fires]
-    B --> C{Transcript > 90%?}
+    B --> C["Transcript size > threshold?"]
     C -->|No| D[Continue normally]
-    C -->|Yes| E{Already triggered?}
+    C -->|Yes| E{Already triggered this session?}
     E -->|Yes| D
-    E -->|No| F[Create flag file]
-    F --> G["Block: force handoff save"]
-    G --> H[Claude saves _active.md]
+    E -->|No| F[Create flag file in /tmp]
+    F --> G["Block Claude: force handoff save"]
+    G --> H[Claude writes _active.md]
     H --> I["User: /clear → /resume"]
 ```
 
-- **Detection**: Measures transcript file size (default 90% of ~500KB max context)
-- **One-shot**: Uses a flag file in `/tmp` to prevent infinite loops — triggers only once per session
-- **Configurable**: Adjust threshold % via `CLAUDE_CONTEXT_THRESHOLD` env var or `/auto-handoff`
-- **Disableable**: Run `/auto-handoff` to turn it off
+### Threshold Configuration
+
+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` | 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 uses real data:
+```
+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
+```
 
-### Configuration
+### Three Ways to Configure
 
+**1. Environment variable** (per-session override):
 ```bash
-# Change threshold (default: 90% of context)
-export CLAUDE_CONTEXT_THRESHOLD=80  # trigger at 80% instead
+# Trigger at 80% instead of the default
+export CLAUDE_CONTEXT_THRESHOLD=80
+```
 
-# Or use the interactive toggle
-/auto-handoff
+**2. Interactive wizard** (`/auto-handoff` command):
+```
+you:    /auto-handoff
+claude: Auto-handoff is ENABLED (threshold: 90%). What would you like to do?
+        1. Disable
+        2. Adjust threshold
+
+you:    [selects "Adjust threshold"]
+claude: Which threshold do you want?
+        1. 90% (Recommended) — Default, maximizes context usage
+        2. 80% — Balance between space and safety
+        3. 75% — Short sessions, saves handoff earlier
+        4. Other — Type a custom value
 ```
 
+**3. Edit the script directly**:
+```bash
+# In .claude/hooks/context-monitor.sh, change the default:
+THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-90}  # change 90 to your value
+```
+
+### Safety Mechanisms
+
+- **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)
+- **Non-destructive**: The hook only blocks and instructs — it never modifies files directly. Claude performs the actual handoff save
+
+### What Happens When It Triggers
+
+When the threshold is hit, Claude receives a block message like:
+
+> ⚠️ AUTO-HANDOFF: Context reached 90% of the limit. You MUST save the handoff NOW.
+
+Claude will then:
+1. Analyze the full conversation
+2. Write the handoff to `.claude/handoffs/_active.md`
+3. Tell you: "Handoff saved automatically. Use `/clear` then `/resume` to continue."
+
 ---
 
 ## Install
@@ -226,7 +279,7 @@ your-project/
     │   ├── save-handoff.md         ← /save-handoff (wizard)
     │   ├── switch-context.md       ← /switch-context (workstream switch)
     │   ├── delete-handoff.md       ← /delete-handoff (remove handoffs)
-    │   └── auto-handoff.md  ← /auto-handoff (on/off)
+    │   └── auto-handoff.md       ← /auto-handoff (on/off + threshold)
     ├── rules/
     │   ├── session-continuity.md   ← Auto-loaded behavioral rules
     │   └── auto-handoff.md         ← Auto-handoff trigger rules
@@ -298,6 +351,45 @@ claude: Where should this session's handoff be saved?
         3. Replace active
 ```
 
+### Auto-handoff in action
+
+```
+you:    [working normally on a long session...]
+claude: [responds to your request]
+
+        ── context reaches 90% ──
+
+claude: ⚠️ AUTO-HANDOFF: Context reached 90% of the limit.
+        Handoff saved automatically.
+        Use /clear then /resume to continue.
+
+you:    /clear
+
+        ── new session ──
+
+you:    /resume
+claude: ## Resuming session
+        [full context restored, continues exactly where you left off]
+```
+
+### Adjusting auto-handoff threshold
+
+```
+you:    /auto-handoff
+claude: Auto-handoff is ENABLED (threshold: 90%). What would you like to do?
+        1. Disable
+        2. Adjust threshold
+
+you:    [selects "Adjust threshold"]
+claude: Which threshold do you want?
+        1. 90% (Recommended)
+        2. 80%
+        3. 75%
+
+you:    [types "95" via Other]
+claude: ✅ Threshold updated to 95%.
+```
+
 ---
 
 ## What Gets Captured
@@ -399,7 +491,8 @@ 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 5 commands natively
+- **Command awareness**: Claude understands all 6 commands natively
+- **Auto-handoff awareness**: When the context monitor triggers, Claude knows exactly what to do — save the handoff immediately without asking
 
 ---
 
@@ -421,9 +514,10 @@ curl -fsSL https://raw.githubusercontent.com/eximIA-Ventures/claude-code-handoff
 
 This will:
 - Overwrite command files with the latest versions
-- Update the rules file
-- Remove legacy Portuguese commands if present (`retomar`, `salvar-handoff`, `trocar-contexto`)
-- **Not touch** your `.claude/handoffs/` data
+- Update rules and hooks to latest
+- Ensure hooks are configured in `settings.json`
+- Remove legacy files if present (`auto-handoff-toggle.md`, Portuguese commands)
+- **Not touch** your `.claude/handoffs/` data or custom threshold settings
 
 ---
 
@@ -435,16 +529,18 @@ curl -fsSL https://raw.githubusercontent.com/eximIA-Ventures/claude-code-handoff
 ```
 
 The uninstaller:
-- Removes all 5 command files
-- Removes the rules file
+- Removes all 6 command files (including legacy `auto-handoff-toggle.md`)
+- Removes rules and hooks
+- Cleans hooks from `settings.json` (requires `jq`)
 - Preserves handoff data if sessions exist (won't delete your session history)
 - Cleans `.gitignore` entries
 - Leaves `CLAUDE.md` unchanged (remove the section manually if desired)
 
 Or remove manually:
 ```bash
-rm .claude/commands/{handoff,resume,save-handoff,switch-context,delete-handoff}.md
-rm .claude/rules/session-continuity.md
+rm .claude/commands/{handoff,resume,save-handoff,switch-context,delete-handoff,auto-handoff}.md
+rm .claude/rules/{session-continuity,auto-handoff}.md
+rm .claude/hooks/{context-monitor,session-cleanup}.sh
 rm -rf .claude/handoffs/  # ⚠️ deletes all session history
 ```
 
@@ -478,6 +574,15 @@ A: The commands automatically summarize older sessions into a "Prior Sessions Su
 **Q: Can I edit the handoff files manually?**
 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 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.
+
+**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.
+
 ---
 
 ## Contributing

package/cli.js

@@ -67,8 +67,8 @@ fs.chmodSync(path.join(CLAUDE_DIR, 'hooks', 'session-cleanup.sh'), 0o755);
 console.log(`  ${YELLOW}[5/10]${NC} Configuring hooks in settings.json...`);
 const settingsPath = path.join(CLAUDE_DIR, 'settings.json');
 const hooksConfig = {
-  Stop: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh', timeout: 10 }] }],
-  SessionStart: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh', timeout: 5 }] }]
+  Stop: [{ hooks: [{ type: 'command', command: '"$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh"', timeout: 10 }] }],
+  SessionStart: [{ hooks: [{ type: 'command', command: '"$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh"', timeout: 5 }] }]
 };
 if (fs.existsSync(settingsPath)) {
   const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));

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

@@ -82,8 +82,8 @@ if [ -f "$SETTINGS_FILE" ]; then
     if command -v jq &>/dev/null; then
       HOOKS_JSON='{
         "hooks": {
-          "Stop": [{"hooks": [{"type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh", "timeout": 10}]}],
-          "SessionStart": [{"hooks": [{"type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh", "timeout": 5}]}]
+          "Stop": [{"hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh\"", "timeout": 10}]}],
+          "SessionStart": [{"hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh\"", "timeout": 5}]}]
         }
       }'
       jq --argjson hooks "$(echo "$HOOKS_JSON" | jq '.hooks')" '. + {hooks: $hooks}' "$SETTINGS_FILE" > "${SETTINGS_FILE}.tmp" && mv "${SETTINGS_FILE}.tmp" "$SETTINGS_FILE"
@@ -102,7 +102,7 @@ if [ -f "$SETTINGS_FILE" ]; then
         "hooks": [
           {
             "type": "command",
-            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh\"",
             "timeout": 10
           }
         ]
@@ -113,7 +113,7 @@ if [ -f "$SETTINGS_FILE" ]; then
         "hooks": [
           {
             "type": "command",
-            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh\"",
             "timeout": 5
           }
         ]
@@ -136,7 +136,7 @@ SETTINGSEOF
         "hooks": [
           {
             "type": "command",
-            "command": "\$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh",
+            "command": "\"\$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh\"",
             "timeout": 10
           }
         ]
@@ -147,7 +147,7 @@ SETTINGSEOF
         "hooks": [
           {
             "type": "command",
-            "command": "\$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh",
+            "command": "\"\$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh\"",
             "timeout": 5
           }
         ]
@@ -169,7 +169,7 @@ else
         "hooks": [
           {
             "type": "command",
-            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh\"",
             "timeout": 10
           }
         ]
@@ -180,7 +180,7 @@ else
         "hooks": [
           {
             "type": "command",
-            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh\"",
             "timeout": 5
           }
         ]

package/package.json

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

package/update.sh

@@ -72,7 +72,7 @@ SETTINGS_FILE="$CLAUDE_DIR/settings.json"
 if [ -f "$SETTINGS_FILE" ]; then
   if ! grep -q "context-monitor" "$SETTINGS_FILE" 2>/dev/null; then
     if command -v jq &>/dev/null; then
-      HOOKS_JSON='{"Stop":[{"hooks":[{"type":"command","command":"$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh","timeout":10}]}],"SessionStart":[{"hooks":[{"type":"command","command":"$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh","timeout":5}]}]}'
+      HOOKS_JSON='{"Stop":[{"hooks":[{"type":"command","command":"\"$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh\"","timeout":10}]}],"SessionStart":[{"hooks":[{"type":"command","command":"\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh\"","timeout":5}]}]}'
       jq --argjson hooks "$HOOKS_JSON" '. + {hooks: $hooks}' "$SETTINGS_FILE" > "${SETTINGS_FILE}.tmp" && mv "${SETTINGS_FILE}.tmp" "$SETTINGS_FILE"
       echo -e "    Hooks added to settings.json"
     else