claude-code-handoff 1.3.2 → 1.5.1

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 |
 |---------|-------------|
@@ -45,9 +45,12 @@ Instead of relying on lossy compression or starting from zero, **claude-code-han
 | `/save-handoff` | Save with options — choose where and how |
 | `/switch-context <topic>` | Switch between parallel workstreams |
 | `/delete-handoff` | Delete one or more saved handoffs |
+| `/auto-handoff` | Enable/disable auto-handoff or adjust threshold |
 
 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.
+
 Session state is stored in `.claude/handoffs/` (gitignored) — each developer keeps their own context, no conflicts.
 
 ---
@@ -59,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%.
 
 ---
 
@@ -152,13 +155,99 @@ graph TD
 
 ---
 
+## Auto-Handoff (Context Monitor)
+
+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 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.
+
+```mermaid
+flowchart TD
+    A[Claude responds] --> B[Stop hook fires]
+    B --> C["Transcript size > threshold?"]
+    C -->|No| D[Continue normally]
+    C -->|Yes| E{Already triggered this session?}
+    E -->|Yes| D
+    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"]
+```
+
+### 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.
+
+| 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 |
+
+The calculation is straightforward:
+```
+MAX_CONTEXT_SIZE = 500000  (500KB — estimated max transcript)
+THRESHOLD = MAX_CONTEXT_SIZE × THRESHOLD_PERCENT / 100
+```
+
+### Three Ways to Configure
+
+**1. Environment variable** (per-session override):
+```bash
+# Trigger at 80% instead of the default
+export CLAUDE_CONTEXT_THRESHOLD=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
+
+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
 
 ### Option A: npx (recommended)
 
 ```bash
 cd your-project
-npx claude-code-handoff@1.3.0
+npx claude-code-handoff@latest
 ```
 
 ### Option B: curl
@@ -182,22 +271,29 @@ cd your-project
 your-project/
 └── .claude/
     ├── commands/
-    │   ├── handoff.md            ← /handoff (auto-save)
-    │   ├── resume.md             ← /resume (interactive picker)
-    │   ├── save-handoff.md       ← /save-handoff (wizard)
-    │   ├── switch-context.md     ← /switch-context (workstream switch)
-    │   └── delete-handoff.md     ← /delete-handoff (remove handoffs)
+    │   ├── handoff.md              ← /handoff (auto-save)
+    │   ├── resume.md               ← /resume (interactive picker)
+    │   ├── 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 + threshold)
     ├── rules/
-    │   └── session-continuity.md ← Auto-loaded behavioral rules
-    └── handoffs/                 ← Session state (gitignored)
-        ├── _active.md            ← Current workstream
-        └── archive/              ← Paused workstreams
+    │   ├── session-continuity.md   ← Auto-loaded behavioral rules
+    │   └── auto-handoff.md         ← Auto-handoff trigger rules
+    ├── hooks/
+    │   ├── context-monitor.sh      ← Stop hook (monitors context size)
+    │   └── session-cleanup.sh      ← SessionStart hook (cleans old flags)
+    ├── settings.json               ← Hook configuration
+    └── handoffs/                   ← Session state (gitignored)
+        ├── _active.md              ← Current workstream
+        └── archive/                ← Paused workstreams
 ```
 
 The installer also:
 - Creates the full `.claude/handoffs/archive/` directory structure
 - Adds `.claude/handoffs/` to `.gitignore`
 - Adds a `Session Continuity` section to `.claude/CLAUDE.md` (creates one if missing)
+- Configures auto-handoff hooks in `.claude/settings.json`
 
 ---
 
@@ -252,6 +348,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
@@ -338,12 +473,12 @@ graph TD
     style SW fill:#7c2d12,stroke:#fb923c,color:#fff
 ```
 
-| | `/handoff` | `/save-handoff` | `/resume` | `/switch-context` |
-|---|---|---|---|---|
-| **When** | Before `/clear` | When you need options | Start of session | Mid-session |
-| **Interactive** | No | Yes (wizard) | Yes (picker) | No (with arg) |
-| **Creates files** | Auto | User chooses | No | Auto |
-| **Reads files** | `_active.md` | `_active.md` + `archive/` | All handoffs | `_active.md` + target |
+| | `/handoff` | `/save-handoff` | `/resume` | `/switch-context` | `/auto-handoff` |
+|---|---|---|---|---|---|
+| **When** | Before `/clear` | When you need options | Start of session | Mid-session | Anytime |
+| **Interactive** | No | Yes (wizard) | Yes (picker) | No (with arg) | Yes (wizard) |
+| **Creates files** | Auto | User chooses | No | Auto | Toggle file |
+| **Reads files** | `_active.md` | `_active.md` + `archive/` | All handoffs | `_active.md` + target | Hook config |
 
 ---
 
@@ -353,7 +488,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
 
 ---
 
@@ -375,9 +511,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
 
 ---
 
@@ -389,16 +526,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
 ```
 
@@ -418,7 +557,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: The context is lost for that session. The previous handoff is still there — you just won't have the latest session recorded.
+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.
 
 **Q: Can I have unlimited workstreams?**
 A: Yes. The `archive/` folder has no limit. Each workstream is a single `.md` file.
@@ -432,6 +571,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 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.
+
+**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

@@ -36,27 +36,54 @@ function copyFile(src, dst) {
 }
 
 // 1. Create directories
-console.log(`  ${YELLOW}[1/8]${NC} Creating directories...`);
+console.log(`  ${YELLOW}[1/10]${NC} Creating directories...`);
 ensureDir(path.join(CLAUDE_DIR, 'commands'));
 ensureDir(path.join(CLAUDE_DIR, 'rules'));
+ensureDir(path.join(CLAUDE_DIR, 'hooks'));
 ensureDir(path.join(CLAUDE_DIR, 'handoffs', 'archive'));
 
 // 2. Copy commands
-console.log(`  ${YELLOW}[2/8]${NC} Installing commands...`);
+console.log(`  ${YELLOW}[2/10]${NC} Installing commands...`);
 copyFile('commands/resume.md', path.join(CLAUDE_DIR, 'commands', 'resume.md'));
 copyFile('commands/save-handoff.md', path.join(CLAUDE_DIR, 'commands', 'save-handoff.md'));
 copyFile('commands/switch-context.md', path.join(CLAUDE_DIR, 'commands', 'switch-context.md'));
 copyFile('commands/handoff.md', path.join(CLAUDE_DIR, 'commands', 'handoff.md'));
 copyFile('commands/delete-handoff.md', path.join(CLAUDE_DIR, 'commands', 'delete-handoff.md'));
+copyFile('commands/auto-handoff.md', path.join(CLAUDE_DIR, 'commands', 'auto-handoff.md'));
 
 // 3. Copy rules
-console.log(`  ${YELLOW}[3/8]${NC} Installing rules...`);
+console.log(`  ${YELLOW}[3/10]${NC} Installing rules...`);
 copyFile('rules/session-continuity.md', path.join(CLAUDE_DIR, 'rules', 'session-continuity.md'));
+copyFile('rules/auto-handoff.md', path.join(CLAUDE_DIR, 'rules', 'auto-handoff.md'));
+
+// 4. Install hooks
+console.log(`  ${YELLOW}[4/10]${NC} Installing hooks...`);
+copyFile('hooks/context-monitor.sh', path.join(CLAUDE_DIR, 'hooks', 'context-monitor.sh'));
+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);
+
+// 5. Configure hooks in settings.json
+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 }] }]
+};
+if (fs.existsSync(settingsPath)) {
+  const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+  if (!JSON.stringify(settings).includes('context-monitor')) {
+    settings.hooks = hooksConfig;
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  }
+} else {
+  fs.writeFileSync(settingsPath, JSON.stringify({ hooks: hooksConfig }, null, 2) + '\n');
+}
 
 // 4. Create initial _active.md
 const activePath = path.join(CLAUDE_DIR, 'handoffs', '_active.md');
 if (!fs.existsSync(activePath)) {
-  console.log(`  ${YELLOW}[4/8]${NC} Creating initial handoff...`);
+  console.log(`  ${YELLOW}[6/10]${NC} Creating initial handoff...`);
   fs.writeFileSync(activePath, `# Session Handoff
 
 > No active session yet. Use \`/handoff\` or \`/save-handoff\` to save your first session state.
@@ -83,11 +110,11 @@ if (!fs.existsSync(activePath)) {
 (none)
 `);
 } else {
-  console.log(`  ${YELLOW}[4/8]${NC} Handoff already exists, keeping it`);
+  console.log(`  ${YELLOW}[6/10]${NC} Handoff already exists, keeping it`);
 }
 
-// 5. Update .gitignore
-console.log(`  ${YELLOW}[5/8]${NC} Updating .gitignore...`);
+// 7. Update .gitignore
+console.log(`  ${YELLOW}[7/10]${NC} Updating .gitignore...`);
 const gitignorePath = path.join(PROJECT_DIR, '.gitignore');
 if (fs.existsSync(gitignorePath)) {
   const content = fs.readFileSync(gitignorePath, 'utf-8');
@@ -98,8 +125,8 @@ if (fs.existsSync(gitignorePath)) {
   fs.writeFileSync(gitignorePath, '# claude-code-handoff (personal session state)\n.claude/handoffs/\n');
 }
 
-// 6. Update CLAUDE.md
-console.log(`  ${YELLOW}[6/8]${NC} Updating CLAUDE.md...`);
+// 8. Update CLAUDE.md
+console.log(`  ${YELLOW}[8/10]${NC} Updating CLAUDE.md...`);
 const claudeMdPath = path.join(CLAUDE_DIR, 'CLAUDE.md');
 const continuityBlock = `## Session Continuity (MANDATORY)
 
@@ -123,20 +150,23 @@ if (fs.existsSync(claudeMdPath)) {
   fs.writeFileSync(claudeMdPath, `# Project Rules\n\n${continuityBlock}\n`);
 }
 
-// 7. Verify
-console.log(`  ${YELLOW}[7/8]${NC} Verifying installation...`);
+// 9. Verify
+console.log(`  ${YELLOW}[9/10]${NC} Verifying installation...`);
 let installed = 0;
-for (const f of ['resume.md', 'save-handoff.md', 'switch-context.md', 'handoff.md', 'delete-handoff.md']) {
+for (const f of ['resume.md', 'save-handoff.md', 'switch-context.md', 'handoff.md', 'delete-handoff.md', 'auto-handoff.md']) {
   if (fs.existsSync(path.join(CLAUDE_DIR, 'commands', f))) installed++;
 }
+let hooksOk = 0;
+if (fs.existsSync(path.join(CLAUDE_DIR, 'hooks', 'context-monitor.sh'))) hooksOk++;
+if (fs.existsSync(path.join(CLAUDE_DIR, 'hooks', 'session-cleanup.sh'))) hooksOk++;
 
 console.log('');
-console.log(`  ${YELLOW}[8/8]${NC} Done!`);
+console.log(`  ${YELLOW}[10/10]${NC} Done!`);
 console.log('');
-if (installed === 5) {
-  console.log(`${GREEN}  Installed successfully! (${installed}/5 commands)${NC}`);
+if (installed === 6 && hooksOk === 2) {
+  console.log(`${GREEN}  Installed successfully! (${installed}/6 commands, ${hooksOk}/2 hooks)${NC}`);
 } else {
-  console.log(`${YELLOW}  Partial install: ${installed}/5 commands${NC}`);
+  console.log(`${YELLOW}  Partial install: ${installed}/6 commands, ${hooksOk}/2 hooks${NC}`);
 }
 console.log('');
 console.log('  Commands available:');
@@ -145,10 +175,16 @@ console.log(`    ${CYAN}/resume${NC}               Resume with wizard`);
 console.log(`    ${CYAN}/save-handoff${NC}         Save session state (wizard)`);
 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('');
 console.log('  Files:');
-console.log('    .claude/commands/     5 command files');
-console.log('    .claude/rules/        session-continuity.md');
+console.log('    .claude/commands/     6 command files');
+console.log('    .claude/rules/        session-continuity.md, auto-handoff.md');
+console.log('    .claude/hooks/        context-monitor.sh, session-cleanup.sh');
 console.log('    .claude/handoffs/     session state (gitignored)');
 console.log('');
 console.log(`  ${YELLOW}Start Claude Code and use /resume to begin.${NC}`);

package/commands/auto-handoff.md

@@ -0,0 +1,37 @@
+# Auto-Handoff
+
+Toggle the automatic handoff context monitor on/off and configure the threshold.
+
+## Instructions
+
+### Step 1: Check current state
+
+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}`).
+
+### Step 2: Present wizard
+
+Use AskUserQuestion:
+- Question: "Auto-handoff está [ATIVADO/DESATIVADO] (threshold: [XX]%). O que deseja fazer?"
+- Options based on current state:
+  - If enabled: "Desativar" / "Ajustar threshold"
+  - If disabled: "Ativar" / "Ativar com threshold customizado"
+
+### 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
+
+### Step 4: Confirm
+
+Show current state after change.

package/hooks/context-monitor.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# Auto-Handoff Context Monitor
+# 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
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+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
+# 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))
+
+INPUT=$(cat)
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty')
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
+
+# Validações
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  exit 0
+fi
+
+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 ' ')
+
+if [ "$SIZE" -lt "$THRESHOLD" ]; then
+  exit 0
+fi
+
+# Flag para não re-triggerar (prevenção de loop infinito)
+FLAG="/tmp/claude_handoff_triggered_${SESSION_ID}"
+if [ -f "$FLAG" ]; then
+  exit 0
+fi
+touch "$FLAG"
+
+# 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."
+}
+HOOKEOF

package/hooks/session-cleanup.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+# Session Cleanup
+# Limpa flag files de sessões anteriores (> 24h) para não acumular lixo no /tmp.
+# Usado como hook "SessionStart" do Claude Code.
+
+find /private/tmp -maxdepth 1 -name "claude_handoff_triggered_*" -mmin +1440 -delete 2>/dev/null
+exit 0

package/install.sh

@@ -45,26 +45,155 @@ download_file() {
 }
 
 # 1. Create directories
-echo -e "  ${YELLOW}[1/8]${NC} Creating directories..."
+echo -e "  ${YELLOW}[1/10]${NC} Creating directories..."
 mkdir -p "$CLAUDE_DIR/commands"
 mkdir -p "$CLAUDE_DIR/rules"
+mkdir -p "$CLAUDE_DIR/hooks"
 mkdir -p "$CLAUDE_DIR/handoffs/archive"
 
 # 2. Download/copy commands
-echo -e "  ${YELLOW}[2/8]${NC} Installing commands..."
+echo -e "  ${YELLOW}[2/10]${NC} Installing commands..."
 download_file "commands/resume.md" "$CLAUDE_DIR/commands/resume.md"
 download_file "commands/save-handoff.md" "$CLAUDE_DIR/commands/save-handoff.md"
 download_file "commands/switch-context.md" "$CLAUDE_DIR/commands/switch-context.md"
 download_file "commands/handoff.md" "$CLAUDE_DIR/commands/handoff.md"
 download_file "commands/delete-handoff.md" "$CLAUDE_DIR/commands/delete-handoff.md"
+download_file "commands/auto-handoff.md" "$CLAUDE_DIR/commands/auto-handoff.md"
 
 # 3. Download/copy rules
-echo -e "  ${YELLOW}[3/8]${NC} Installing rules..."
+echo -e "  ${YELLOW}[3/10]${NC} Installing 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"
 
-# 4. Create initial _active.md if not exists
+# 4. Install hooks (auto-handoff context monitor)
+echo -e "  ${YELLOW}[4/10]${NC} Installing hooks..."
+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"
+
+# 5. Configure hooks in settings.json
+echo -e "  ${YELLOW}[5/10]${NC} Configuring hooks in settings.json..."
+SETTINGS_FILE="$CLAUDE_DIR/settings.json"
+if [ -f "$SETTINGS_FILE" ]; then
+  # Check if hooks already configured
+  if ! grep -q "context-monitor" "$SETTINGS_FILE" 2>/dev/null; then
+    # Merge hooks into existing settings.json using jq if available
+    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}]}]
+        }
+      }'
+      jq --argjson hooks "$(echo "$HOOKS_JSON" | jq '.hooks')" '. + {hooks: $hooks}' "$SETTINGS_FILE" > "${SETTINGS_FILE}.tmp" && mv "${SETTINGS_FILE}.tmp" "$SETTINGS_FILE"
+    else
+      # Fallback: rewrite settings.json preserving existing keys
+      echo -e "  ${YELLOW}  ⚠ jq not found. Adding hooks config manually...${NC}"
+      # Read existing content, strip trailing brace, append hooks
+      EXISTING=$(cat "$SETTINGS_FILE")
+      # Remove trailing } and whitespace
+      EXISTING=$(echo "$EXISTING" | sed '$ s/}$//')
+      cat > "$SETTINGS_FILE" << 'SETTINGSEOF'
+{
+  "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
+          }
+        ]
+      }
+    ]
+  }
+}
+SETTINGSEOF
+      # Merge with original using jq-less approach: just add hooks key
+      # Since we can't reliably merge JSON without jq, write a complete file
+      # preserving the language setting if it exists
+      LANG_SETTING=$(echo "$EXISTING" | grep '"language"' | head -1 | sed 's/,$//')
+      if [ -n "$LANG_SETTING" ]; then
+        cat > "$SETTINGS_FILE" << SETTINGSEOF
+{
+  ${LANG_SETTING},
+  "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
+          }
+        ]
+      }
+    ]
+  }
+}
+SETTINGSEOF
+      fi
+    fi
+  fi
+else
+  # Create new settings.json with hooks
+  cat > "$SETTINGS_FILE" << 'SETTINGSEOF'
+{
+  "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
+          }
+        ]
+      }
+    ]
+  }
+}
+SETTINGSEOF
+fi
+
+# 6. Create initial _active.md if not exists
 if [ ! -f "$CLAUDE_DIR/handoffs/_active.md" ]; then
-  echo -e "  ${YELLOW}[4/8]${NC} Creating initial handoff..."
+  echo -e "  ${YELLOW}[6/10]${NC} Creating initial handoff..."
   cat > "$CLAUDE_DIR/handoffs/_active.md" << 'HANDOFF'
 # Session Handoff
 
@@ -92,11 +221,11 @@ if [ ! -f "$CLAUDE_DIR/handoffs/_active.md" ]; then
 (none)
 HANDOFF
 else
-  echo -e "  ${YELLOW}[4/8]${NC} Handoff already exists, keeping it"
+  echo -e "  ${YELLOW}[6/10]${NC} Handoff already exists, keeping it"
 fi
 
-# 5. Add to .gitignore
-echo -e "  ${YELLOW}[5/8]${NC} Updating .gitignore..."
+# 7. Add to .gitignore
+echo -e "  ${YELLOW}[7/10]${NC} Updating .gitignore..."
 GITIGNORE="$PROJECT_DIR/.gitignore"
 if [ -f "$GITIGNORE" ]; then
   if ! grep -q ".claude/handoffs/" "$GITIGNORE" 2>/dev/null; then
@@ -109,8 +238,8 @@ else
   echo ".claude/handoffs/" >> "$GITIGNORE"
 fi
 
-# 6. Add to CLAUDE.md
-echo -e "  ${YELLOW}[6/8]${NC} Updating CLAUDE.md..."
+# 8. Add to CLAUDE.md
+echo -e "  ${YELLOW}[8/10]${NC} Updating CLAUDE.md..."
 CLAUDE_MD="$CLAUDE_DIR/CLAUDE.md"
 CONTINUITY_BLOCK='## Session Continuity (MANDATORY)
 
@@ -150,20 +279,23 @@ Use `/handoff` before `/clear`. Use `/resume` to pick up. Use `/switch-context <
 CLAUDEMD
 fi
 
-# 7. Summary
-echo -e "  ${YELLOW}[7/8]${NC} Verifying installation..."
+# 9. Summary
+echo -e "  ${YELLOW}[9/10]${NC} Verifying installation..."
 INSTALLED=0
-for f in resume.md save-handoff.md switch-context.md handoff.md delete-handoff.md; do
+for f in resume.md save-handoff.md switch-context.md handoff.md delete-handoff.md auto-handoff.md; do
   [ -f "$CLAUDE_DIR/commands/$f" ] && INSTALLED=$((INSTALLED + 1))
 done
+HOOKS_OK=0
+[ -f "$CLAUDE_DIR/hooks/context-monitor.sh" ] && HOOKS_OK=$((HOOKS_OK + 1))
+[ -f "$CLAUDE_DIR/hooks/session-cleanup.sh" ] && HOOKS_OK=$((HOOKS_OK + 1))
 
 echo ""
-echo -e "  ${YELLOW}[8/8]${NC} Done!"
+echo -e "  ${YELLOW}[10/10]${NC} Done!"
 echo ""
-if [ "$INSTALLED" -eq 5 ]; then
-  echo -e "${GREEN}  Installed successfully! ($INSTALLED/5 commands)${NC}"
+if [ "$INSTALLED" -eq 6 ] && [ "$HOOKS_OK" -eq 2 ]; then
+  echo -e "${GREEN}  Installed successfully! ($INSTALLED/6 commands, $HOOKS_OK/2 hooks)${NC}"
 else
-  echo -e "${YELLOW}  Partial install: $INSTALLED/5 commands${NC}"
+  echo -e "${YELLOW}  Partial install: $INSTALLED/6 commands, $HOOKS_OK/2 hooks${NC}"
 fi
 echo ""
 echo -e "  Commands available:"
@@ -172,10 +304,16 @@ echo -e "    ${CYAN}/resume${NC}               Resume with wizard"
 echo -e "    ${CYAN}/save-handoff${NC}         Save session state (wizard)"
 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 ""
 echo -e "  Files:"
-echo -e "    .claude/commands/     5 command files"
-echo -e "    .claude/rules/        session-continuity.md"
+echo -e "    .claude/commands/     6 command files"
+echo -e "    .claude/rules/        session-continuity.md, auto-handoff.md"
+echo -e "    .claude/hooks/        context-monitor.sh, session-cleanup.sh"
 echo -e "    .claude/handoffs/     session state (gitignored)"
 echo ""
 echo -e "  ${YELLOW}Start Claude Code and use /resume to begin.${NC}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-handoff",
-  "version": "1.3.2",
+  "version": "1.5.1",
   "description": "Session continuity for Claude Code — 5 slash commands to save, resume, delete, and switch workstreams across /clear",
   "bin": {
     "claude-code-handoff": "./cli.js"
@@ -12,6 +12,7 @@
     "update.sh",
     "commands/",
     "rules/",
+    "hooks/",
     "LICENSE",
     "README.md"
   ],

package/rules/auto-handoff.md

@@ -0,0 +1,13 @@
+# Auto-Handoff Rule
+
+When you receive a message containing "AUTO-HANDOFF" from a hook, you MUST:
+
+1. IMMEDIATELY stop any current task
+2. Analyze the full conversation and extract all relevant information
+3. Write the handoff to `.claude/handoffs/_active.md` following the standard template
+4. Tell the user the handoff was auto-saved and they should `/clear` then `/resume`
+
+Do NOT:
+- Continue with previous work
+- Ask the user for permission first
+- Skip any section of the handoff template

package/uninstall.sh

@@ -27,39 +27,61 @@ if [ ! -d "$CLAUDE_DIR" ]; then
 fi
 
 # 1. Remove commands
-echo -e "  ${YELLOW}[1/4]${NC} Removing commands..."
+echo -e "  ${YELLOW}[1/6]${NC} Removing commands..."
 rm -f "$CLAUDE_DIR/commands/handoff.md"
 rm -f "$CLAUDE_DIR/commands/resume.md"
 rm -f "$CLAUDE_DIR/commands/save-handoff.md"
 rm -f "$CLAUDE_DIR/commands/switch-context.md"
 rm -f "$CLAUDE_DIR/commands/delete-handoff.md"
+rm -f "$CLAUDE_DIR/commands/auto-handoff.md"
+# Also remove legacy commands if present
+rm -f "$CLAUDE_DIR/commands/auto-handoff-toggle.md"
 # Also remove legacy Portuguese commands if present
 rm -f "$CLAUDE_DIR/commands/retomar.md"
 rm -f "$CLAUDE_DIR/commands/salvar-handoff.md"
 rm -f "$CLAUDE_DIR/commands/trocar-contexto.md"
 
 # 2. Remove rules
-echo -e "  ${YELLOW}[2/4]${NC} Removing rules..."
+echo -e "  ${YELLOW}[2/6]${NC} Removing rules..."
 rm -f "$CLAUDE_DIR/rules/session-continuity.md"
+rm -f "$CLAUDE_DIR/rules/auto-handoff.md"
 
-# 3. Remove handoffs (with confirmation)
+# 3. Remove hooks
+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-disabled"
+rmdir "$CLAUDE_DIR/hooks" 2>/dev/null || true
+
+# 4. Clean hooks from settings.json
+echo -e "  ${YELLOW}[4/6]${NC} Cleaning settings.json..."
+SETTINGS_FILE="$CLAUDE_DIR/settings.json"
+if [ -f "$SETTINGS_FILE" ] && grep -q "context-monitor" "$SETTINGS_FILE" 2>/dev/null; then
+  if command -v jq &>/dev/null; then
+    jq 'del(.hooks)' "$SETTINGS_FILE" > "${SETTINGS_FILE}.tmp" && mv "${SETTINGS_FILE}.tmp" "$SETTINGS_FILE"
+  else
+    echo -e "    ${YELLOW}⚠ jq not found — remove hooks from .claude/settings.json manually${NC}"
+  fi
+fi
+
+# 5. Remove handoffs (with confirmation)
 if [ -d "$CLAUDE_DIR/handoffs" ]; then
   # Check if there's actual content
   ACTIVE_CONTENT=$(cat "$CLAUDE_DIR/handoffs/_active.md" 2>/dev/null || echo "")
   if echo "$ACTIVE_CONTENT" | grep -q "No active session yet\|not started"; then
-    echo -e "  ${YELLOW}[3/4]${NC} Removing handoffs (no session data)..."
+    echo -e "  ${YELLOW}[5/6]${NC} Removing handoffs (no session data)..."
     rm -rf "$CLAUDE_DIR/handoffs"
   else
-    echo -e "  ${YELLOW}[3/4]${NC} ${RED}Handoffs contain session data!${NC}"
+    echo -e "  ${YELLOW}[5/6]${NC} ${RED}Handoffs contain session data!${NC}"
     echo -e "        Kept: .claude/handoffs/"
     echo -e "        Remove manually with: rm -rf .claude/handoffs/"
   fi
 else
-  echo -e "  ${YELLOW}[3/4]${NC} No handoffs directory found"
+  echo -e "  ${YELLOW}[5/6]${NC} No handoffs directory found"
 fi
 
-# 4. Clean .gitignore
-echo -e "  ${YELLOW}[4/4]${NC} Cleaning .gitignore..."
+# 6. Clean .gitignore
+echo -e "  ${YELLOW}[6/6]${NC} Cleaning .gitignore..."
 GITIGNORE="$PROJECT_DIR/.gitignore"
 if [ -f "$GITIGNORE" ]; then
   # Remove the handoff lines

package/update.sh

@@ -45,20 +45,50 @@ download_file() {
 }
 
 # 1. Update commands
-echo -e "  ${YELLOW}[1/3]${NC} Updating commands..."
+echo -e "  ${YELLOW}[1/5]${NC} Updating commands..."
 download_file "commands/handoff.md" "$CLAUDE_DIR/commands/handoff.md"
 download_file "commands/resume.md" "$CLAUDE_DIR/commands/resume.md"
 download_file "commands/save-handoff.md" "$CLAUDE_DIR/commands/save-handoff.md"
 download_file "commands/switch-context.md" "$CLAUDE_DIR/commands/switch-context.md"
+download_file "commands/delete-handoff.md" "$CLAUDE_DIR/commands/delete-handoff.md"
+download_file "commands/auto-handoff.md" "$CLAUDE_DIR/commands/auto-handoff.md"
 
 # 2. Update rules
-echo -e "  ${YELLOW}[2/3]${NC} Updating rules..."
+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. Remove legacy Portuguese commands if present
-echo -e "  ${YELLOW}[3/3]${NC} Cleaning up legacy files..."
+# 3. Update hooks
+echo -e "  ${YELLOW}[3/5]${NC} Updating hooks..."
+mkdir -p "$CLAUDE_DIR/hooks"
+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"
+
+# 4. Ensure hooks are configured in settings.json
+echo -e "  ${YELLOW}[4/5]${NC} Checking settings.json hooks..."
+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}]}]}'
+      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
+      echo -e "    ${YELLOW}⚠ jq not found — add hooks to .claude/settings.json manually${NC}"
+    fi
+  else
+    echo -e "    Hooks already configured"
+  fi
+else
+  echo -e "    ${YELLOW}⚠ settings.json not found — run install first${NC}"
+fi
+
+# 5. Remove legacy files if present
+echo -e "  ${YELLOW}[5/5]${NC} Cleaning up legacy files..."
 CLEANED=0
-for f in retomar.md salvar-handoff.md trocar-contexto.md; do
+for f in retomar.md salvar-handoff.md trocar-contexto.md auto-handoff-toggle.md; do
   if [ -f "$CLAUDE_DIR/commands/$f" ]; then
     rm -f "$CLAUDE_DIR/commands/$f"
     CLEANED=$((CLEANED + 1))