claude-code-handoff 1.6.0 → 1.8.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.
@@ -176,19 +178,34 @@ flowchart TD
     H --> I["User: /clear → /resume"]
 ```
 
+### Plan Selection
+
+The context window varies by Claude plan. The hook adapts automatically based on your plan configuration:
+
+| Plan | Context Window | Value |
+|------|---------------|-------|
+| **Pro / Max / Team** | 200K tokens | `MAX_CONTEXT_TOKENS=200000` (default) |
+| **Enterprise** | 500K tokens | `MAX_CONTEXT_TOKENS=500000` |
+| **Custom** | Any value | Set via `/auto-handoff` or env var |
+
+Configure your plan via the `/auto-handoff` wizard or set the environment variable:
+```bash
+export CLAUDE_MAX_CONTEXT=500000  # Enterprise
+```
+
 ### 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.
+The threshold is configured as a **percentage of your plan's 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 |
+| Preset | Value | Triggers at (200K) | Triggers at (500K) | Best for |
+|--------|-------|---------------------|---------------------|----------|
+| **90% (default)** | `THRESHOLD_PERCENT=90` | 180K tokens | 450K tokens | Maximizing context usage |
+| **80%** | `THRESHOLD_PERCENT=80` | 160K tokens | 400K tokens | Balance between space and safety |
+| **75%** | `THRESHOLD_PERCENT=75` | 150K tokens | 375K tokens | Short sessions, early handoff |
 
 The calculation uses real data:
 ```
-MAX_CONTEXT_TOKENS = 200000   (Claude Code's context window)
+MAX_CONTEXT_TOKENS = 200000 (or 500000 for Enterprise, or custom)
 THRESHOLD = MAX_CONTEXT_TOKENS × THRESHOLD_PERCENT / 100
 
 # The hook reads input_tokens from the last assistant message in the JSONL
@@ -197,31 +214,39 @@ THRESHOLD = MAX_CONTEXT_TOKENS × THRESHOLD_PERCENT / 100
 
 ### Three Ways to Configure
 
-**1. Environment variable** (per-session override):
+**1. Environment variables** (per-session override):
 ```bash
-# Trigger at 80% instead of the default
-export CLAUDE_CONTEXT_THRESHOLD=80
+export CLAUDE_MAX_CONTEXT=500000    # Enterprise plan (500K)
+export CLAUDE_CONTEXT_THRESHOLD=80  # Trigger at 80%
 ```
 
 **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
+claude: Auto-handoff is DISABLED (plan: Pro/Max/Team, threshold: 90%).
+        What would you like to do?
+        1. Enable
+        2. Enable with custom configuration
 
-you:    [selects "Adjust threshold"]
+you:    [selects "Enable with custom configuration"]
+claude: Which is your Claude plan?
+        1. Pro / Max / Team — 200K tokens
+        2. Enterprise — 500K tokens
+        3. Other — Type a custom value
+
+you:    [selects plan]
 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
+        1. 90% (Recommended)
+        2. 80%
+        3. 75%
         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
+# In .claude/hooks/context-monitor.sh, change the defaults:
+MAX_CONTEXT_TOKENS=${CLAUDE_MAX_CONTEXT:-200000}   # change 200000 to your value
+THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-90}   # change 90 to your value
 ```
 
 ### Safety Mechanisms
@@ -285,7 +310,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 +586,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/commands/auto-handoff.md

@@ -1,6 +1,6 @@
 # Auto-Handoff
 
-Toggle the automatic handoff context monitor on/off and configure the threshold.
+Toggle the automatic handoff context monitor on/off, configure threshold, and select your Claude plan.
 
 ## Instructions
 
@@ -10,28 +10,55 @@ Check if `.claude/hooks/.auto-handoff-disabled` exists:
 - If exists → currently DISABLED
 - If not exists → currently ENABLED
 
-Also read the current `THRESHOLD_PERCENT` value from `.claude/hooks/context-monitor.sh` (the default value in `THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-XX}`).
+Also read from `.claude/hooks/context-monitor.sh`:
+- `THRESHOLD_PERCENT` value (the default in `THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-XX}`)
+- `MAX_CONTEXT_TOKENS` value (the default in `MAX_CONTEXT_TOKENS=${CLAUDE_MAX_CONTEXT:-XXXXXX}`)
+
+Derive the plan name from MAX_CONTEXT_TOKENS:
+- 200000 → "Pro/Max/Team"
+- 500000 → "Enterprise"
+- other → "Custom (XXXk)"
 
 ### Step 2: Present wizard
 
 Use AskUserQuestion:
-- Question: "Auto-handoff está [ATIVADO/DESATIVADO] (threshold: [XX]%). O que deseja fazer?"
+- Question: "Auto-handoff está [ATIVADO/DESATIVADO] (plano: [PLAN], threshold: [XX]%). O que deseja fazer?"
 - Options based on current state:
-  - If enabled: "Desativar" / "Ajustar threshold"
-  - If disabled: "Ativar" / "Ativar com threshold customizado"
+  - If enabled: "Desativar" / "Ajustar threshold" / "Alterar plano"
+  - If disabled: "Ativar" / "Ativar com configuração customizada"
 
 ### Step 3: Execute
 
-- Toggle: create or delete `.claude/hooks/.auto-handoff-disabled`
-- Threshold: If user chose to adjust threshold, ask with AskUserQuestion:
-  - Question: "Qual threshold deseja usar?"
-  - Options:
-    - "90% (Recomendado)" — Padrão, maximiza o uso do contexto
-    - "80%" — Equilíbrio entre espaço e segurança
-    - "75%" — Para sessões curtas, salva handoff mais cedo
-  - The user can also type a custom value via "Other"
-  - Update the `THRESHOLD_PERCENT` default value in `context-monitor.sh` by changing `THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-XX}` to the chosen value
+#### Toggle (Ativar/Desativar):
+- Create or delete `.claude/hooks/.auto-handoff-disabled`
+
+#### Ajustar threshold:
+Ask with AskUserQuestion:
+- Question: "Qual threshold deseja usar?"
+- Options:
+  - "90% (Recomendado)" — Padrão, maximiza o uso do contexto
+  - "80%" — Equilíbrio entre espaço e segurança
+  - "75%" — Para sessões curtas, salva handoff mais cedo
+- The user can also type a custom value via "Other"
+- Update the `THRESHOLD_PERCENT` default value in `context-monitor.sh` by changing `THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-XX}` to the chosen value
+
+#### Alterar plano:
+Ask with AskUserQuestion:
+- Question: "Qual seu plano do Claude?"
+- Options:
+  - "Pro / Max / Team" — 200K tokens de contexto
+  - "Enterprise" — 500K tokens de contexto (Sonnet 4.5)
+- The user can also type a custom value via "Other" (e.g., "1000000" for 1M API context)
+- 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`
 
 ### Step 4: Confirm
 
-Show current state after change.
+Show current state after change:
+```
+Auto-handoff: [ATIVADO/DESATIVADO]
+Plano: [plan name] ([MAX_CONTEXT_TOKENS] tokens)
+Threshold: [XX]% (triggers at [calculated tokens] tokens)
+```

package/hooks/context-monitor.sh

@@ -9,8 +9,9 @@ if [ -f "$SCRIPT_DIR/.auto-handoff-disabled" ]; then
   exit 0
 fi
 
-# Contexto máximo do Claude Code (tokens)
-MAX_CONTEXT_TOKENS=200000
+# Contexto máximo do Claude Code (tokens). Varia por plano:
+# Pro/Max/Team: 200000 | Enterprise: 500000 | Custom: qualquer valor
+MAX_CONTEXT_TOKENS=${CLAUDE_MAX_CONTEXT:-200000}
 # Threshold configurável (% do contexto). 90% padrão — maximiza uso do contexto
 THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-90}
 THRESHOLD_TOKENS=$((MAX_CONTEXT_TOKENS * THRESHOLD_PERCENT / 100))

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