claude-code-handoff 1.8.1 → 2.0.0

package/README.md

@@ -253,7 +253,7 @@ THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-90}   # change 90 to your value
 
 - **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)
+- **Opt-in design**: Auto-handoff only runs when `.claude/hooks/.auto-handoff-enabled` exists (created by `/auto-handoff`). No file = disabled by default
 - **Non-destructive**: The hook only blocks and instructs — it never modifies files directly. Claude performs the actual handoff save
 
 ### What Happens When It Triggers
@@ -311,7 +311,7 @@ your-project/
     ├── hooks/
     │   ├── context-monitor.sh      ← Stop hook (monitors context size)
     │   ├── session-cleanup.sh      ← SessionStart hook (cleans old flags)
-    │   └── .auto-handoff-disabled  ← Disable flag (remove to enable)
+    │   └── .auto-handoff-enabled   ← Enable flag (created by /auto-handoff)
     ├── settings.json               ← Hook configuration
     └── handoffs/                   ← Session state (gitignored)
         ├── _active.md              ← Current workstream
@@ -604,7 +604,7 @@ A: Absolutely. They're plain markdown. You can add notes, reorder next steps, or
 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.
+A: Yes. Run `/auto-handoff` and select "Disable", or manually delete `.claude/hooks/.auto-handoff-enabled`. Without this file, auto-handoff is off.
 
 **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.

package/cli.js

@@ -3,24 +3,35 @@
 const fs = require('fs');
 const path = require('path');
 
-const GREEN = '\x1b[32m';
-const YELLOW = '\x1b[33m';
-const CYAN = '\x1b[36m';
+// Colors (RGB)
+const AMBER = '\x1b[38;2;245;158;11m';
+const GREEN = '\x1b[38;2;16;185;129m';
+const RED = '\x1b[38;2;239;68;68m';
+const CYAN = '\x1b[38;2;34;211;238m';
+const WHITE = '\x1b[37m';
+const GRAY = '\x1b[90m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
 const NC = '\x1b[0m';
 
+const ok   = (msg) => console.log(`  ${GREEN}✓${NC} ${msg}`);
+const fail = (msg) => console.log(`  ${RED}✗${NC} ${msg}`);
+const info = (msg) => console.log(`  ${GRAY}${msg}${NC}`);
+const head = (msg) => console.log(`\n  ${AMBER}${BOLD}${msg}${NC}`);
+
 const PROJECT_DIR = process.cwd();
 const CLAUDE_DIR = path.join(PROJECT_DIR, '.claude');
 const SCRIPT_DIR = __dirname;
 
+// ─── Banner ───────────────────────────────────────────
 console.log('');
-console.log(`${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
-console.log(`${CYAN}  claude-code-handoff — Session Continuity${NC}`);
-console.log(`${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
-console.log('');
-console.log(`  Project: ${GREEN}${PROJECT_DIR}${NC}`);
+console.log(`  ${AMBER}${BOLD}┌──────────────────────────────────────┐${NC}`);
+console.log(`  ${AMBER}${BOLD}│${NC}   ${WHITE}${BOLD}claude-code-handoff${NC}  ${DIM}v1.9${NC}        ${AMBER}${BOLD}│${NC}`);
+console.log(`  ${AMBER}${BOLD}│${NC}   ${GRAY}Session Continuity for Claude Code${NC}  ${AMBER}${BOLD}│${NC}`);
+console.log(`  ${AMBER}${BOLD}└──────────────────────────────────────┘${NC}`);
 console.log('');
+info(`Project: ${WHITE}${PROJECT_DIR}${NC}`);
 
-// Helper
 function ensureDir(dir) {
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 }
@@ -30,48 +41,62 @@ function copyFile(src, dst) {
   if (fs.existsSync(srcPath)) {
     fs.copyFileSync(srcPath, dst);
   } else {
-    console.error(`  Error: ${src} not found in package`);
+    fail(`${src} not found in package`);
     process.exit(1);
   }
 }
 
-// 1. Create directories
-console.log(`  ${YELLOW}[1/10]${NC} Creating directories...`);
+// ─── Pre-flight ───────────────────────────────────────
+head('Pre-flight');
+
+const monitorPath = path.join(CLAUDE_DIR, 'hooks', 'context-monitor.sh');
+let isReinstall = false;
+let savedThreshold = '';
+let savedMaxContext = '';
+if (fs.existsSync(monitorPath)) {
+  isReinstall = true;
+  const oldContent = fs.readFileSync(monitorPath, 'utf-8');
+  const thresholdMatch = oldContent.match(/CLAUDE_CONTEXT_THRESHOLD:-(\d+)/);
+  const maxContextMatch = oldContent.match(/CLAUDE_MAX_CONTEXT:-(\d+)/);
+  if (thresholdMatch) savedThreshold = thresholdMatch[1];
+  if (maxContextMatch) savedMaxContext = maxContextMatch[1];
+}
+
+if (isReinstall) {
+  info('Existing installation found. Upgrading...');
+} else {
+  ok('Fresh install');
+}
+
+// ─── Directories ──────────────────────────────────────
+head('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'));
+ok('Directory structure created');
+
+// ─── Commands ─────────────────────────────────────────
+head('Installing commands');
 
-// 2. Copy 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'));
+ok('6 slash commands installed');
+
+// ─── Rules ────────────────────────────────────────────
+head('Installing rules');
 
-// 3. Copy 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'));
+ok('Behavioral rules installed');
 
-// 4. Install hooks
-console.log(`  ${YELLOW}[4/10]${NC} Installing hooks...`);
-
-// Detect reinstall: save user's custom settings before overwriting
-const monitorPath = path.join(CLAUDE_DIR, 'hooks', 'context-monitor.sh');
-let isReinstall = false;
-let savedThreshold = '';
-let savedMaxContext = '';
-if (fs.existsSync(monitorPath)) {
-  isReinstall = true;
-  const oldContent = fs.readFileSync(monitorPath, 'utf-8');
-  const thresholdMatch = oldContent.match(/CLAUDE_CONTEXT_THRESHOLD:-(\d+)/);
-  const maxContextMatch = oldContent.match(/CLAUDE_MAX_CONTEXT:-(\d+)/);
-  if (thresholdMatch) savedThreshold = thresholdMatch[1];
-  if (maxContextMatch) savedMaxContext = maxContextMatch[1];
-}
+// ─── Hooks ────────────────────────────────────────────
+head('Installing hooks');
 
 copyFile('hooks/context-monitor.sh', monitorPath);
 copyFile('hooks/session-cleanup.sh', path.join(CLAUDE_DIR, 'hooks', 'session-cleanup.sh'));
@@ -79,25 +104,26 @@ fs.chmodSync(monitorPath, 0o755);
 fs.chmodSync(path.join(CLAUDE_DIR, 'hooks', 'session-cleanup.sh'), 0o755);
 
 if (isReinstall) {
-  // Restore user's custom settings
   let content = fs.readFileSync(monitorPath, 'utf-8');
   if (savedThreshold && savedThreshold !== '90') {
     content = content.replace('CLAUDE_CONTEXT_THRESHOLD:-90', `CLAUDE_CONTEXT_THRESHOLD:-${savedThreshold}`);
-    console.log(`    Preserved threshold: ${CYAN}${savedThreshold}%${NC}`);
+    ok(`Preserved threshold: ${CYAN}${savedThreshold}%${NC}`);
   }
   if (savedMaxContext && savedMaxContext !== '200000') {
     content = content.replace('CLAUDE_MAX_CONTEXT:-200000', `CLAUDE_MAX_CONTEXT:-${savedMaxContext}`);
-    console.log(`    Preserved max context: ${CYAN}${savedMaxContext} tokens${NC}`);
+    ok(`Preserved max context: ${CYAN}${savedMaxContext} tokens${NC}`);
   }
   fs.writeFileSync(monitorPath, content);
-  // Don't touch .auto-handoff-disabled — preserve user's on/off choice
-} else {
-  // Fresh install: 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...`);
+// Clean up legacy disabled flag
+const legacyDisabled = path.join(CLAUDE_DIR, 'hooks', '.auto-handoff-disabled');
+if (fs.existsSync(legacyDisabled)) fs.unlinkSync(legacyDisabled);
+ok('Context monitor + session cleanup hooks');
+
+// ─── Settings ─────────────────────────────────────────
+head('Configuring 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 }] }],
@@ -108,15 +134,20 @@ if (fs.existsSync(settingsPath)) {
   if (!JSON.stringify(settings).includes('context-monitor')) {
     settings.hooks = hooksConfig;
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    ok('Hooks added to existing settings.json');
+  } else {
+    ok('Hooks already configured');
   }
 } else {
   fs.writeFileSync(settingsPath, JSON.stringify({ hooks: hooksConfig }, null, 2) + '\n');
+  ok('settings.json created with hooks');
 }
 
-// 4. Create initial _active.md
+// ─── Handoff ──────────────────────────────────────────
+head('Setting up handoff storage');
+
 const activePath = path.join(CLAUDE_DIR, 'handoffs', '_active.md');
 if (!fs.existsSync(activePath)) {
-  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.
@@ -142,24 +173,31 @@ if (!fs.existsSync(activePath)) {
 ## Decisions Registry
 (none)
 `);
+  ok('Initial handoff template created');
 } else {
-  console.log(`  ${YELLOW}[6/10]${NC} Handoff already exists, keeping it`);
+  ok('Existing handoff preserved');
 }
 
-// 7. Update .gitignore
-console.log(`  ${YELLOW}[7/10]${NC} Updating .gitignore...`);
+// ─── Gitignore ────────────────────────────────────────
+head('Updating .gitignore');
+
 const gitignorePath = path.join(PROJECT_DIR, '.gitignore');
 if (fs.existsSync(gitignorePath)) {
   const content = fs.readFileSync(gitignorePath, 'utf-8');
   if (!content.includes('.claude/handoffs/')) {
     fs.appendFileSync(gitignorePath, '\n# claude-code-handoff (personal session state)\n.claude/handoffs/\n');
+    ok('Added .claude/handoffs/ to .gitignore');
+  } else {
+    ok('Already in .gitignore');
   }
 } else {
   fs.writeFileSync(gitignorePath, '# claude-code-handoff (personal session state)\n.claude/handoffs/\n');
+  ok('.gitignore created');
 }
 
-// 8. Update CLAUDE.md
-console.log(`  ${YELLOW}[8/10]${NC} Updating CLAUDE.md...`);
+// ─── CLAUDE.md ────────────────────────────────────────
+head('Updating CLAUDE.md');
+
 const claudeMdPath = path.join(CLAUDE_DIR, 'CLAUDE.md');
 const continuityBlock = `## Session Continuity (MANDATORY)
 
@@ -178,13 +216,26 @@ if (fs.existsSync(claudeMdPath)) {
     } else {
       fs.appendFileSync(claudeMdPath, '\n' + continuityBlock + '\n');
     }
+    ok('Session Continuity section added');
+  } else {
+    ok('Session Continuity already present');
   }
 } else {
   fs.writeFileSync(claudeMdPath, `# Project Rules\n\n${continuityBlock}\n`);
+  ok('CLAUDE.md created');
 }
 
-// 9. Verify
-console.log(`  ${YELLOW}[9/10]${NC} Verifying installation...`);
+// ─── Legacy cleanup ──────────────────────────────────
+let cleaned = 0;
+for (const f of ['retomar.md', 'salvar-handoff.md', 'trocar-contexto.md', 'auto-handoff-toggle.md']) {
+  const fp = path.join(CLAUDE_DIR, 'commands', f);
+  if (fs.existsSync(fp)) { fs.unlinkSync(fp); cleaned++; }
+}
+if (cleaned > 0) info(`Removed ${cleaned} legacy command(s)`);
+
+// ─── Verify ───────────────────────────────────────────
+head('Verifying');
+
 let installed = 0;
 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++;
@@ -193,31 +244,28 @@ 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}[10/10]${NC} Done!`);
-console.log('');
 if (installed === 6 && hooksOk === 2) {
-  console.log(`${GREEN}  Installed successfully! (${installed}/6 commands, ${hooksOk}/2 hooks)${NC}`);
+  ok(`${installed}/6 commands, ${hooksOk}/2 hooks`);
 } else {
-  console.log(`${YELLOW}  Partial install: ${installed}/6 commands, ${hooksOk}/2 hooks${NC}`);
+  fail(`Partial: ${installed}/6 commands, ${hooksOk}/2 hooks`);
 }
+
+// ─── Done ─────────────────────────────────────────────
 console.log('');
-console.log('  Commands available:');
-console.log(`    ${CYAN}/handoff${NC}              Auto-save session (no wizard)`);
-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(`  ${AMBER}${BOLD}════════════════════════════════════════${NC}`);
+console.log(`  ${GREEN}${BOLD}  Installed successfully!${NC}`);
+console.log(`  ${AMBER}${BOLD}════════════════════════════════════════${NC}`);
 console.log('');
-console.log(`  Auto-handoff: ${YELLOW}(beta — disabled by default)${NC}`);
-console.log(`    Use ${CYAN}/auto-handoff${NC} to enable and configure threshold`);
+console.log(`  ${WHITE}${BOLD}Commands:${NC}`);
+console.log(`    ${CYAN}/handoff${NC}            ${GRAY}Auto-save session${NC}`);
+console.log(`    ${CYAN}/resume${NC}             ${GRAY}Resume with wizard${NC}`);
+console.log(`    ${CYAN}/save-handoff${NC}       ${GRAY}Save with options${NC}`);
+console.log(`    ${CYAN}/switch-context${NC}     ${GRAY}Switch workstream${NC}`);
+console.log(`    ${CYAN}/delete-handoff${NC}     ${GRAY}Delete handoff(s)${NC}`);
+console.log(`    ${CYAN}/auto-handoff${NC}       ${GRAY}Toggle auto-handoff${NC}`);
 console.log('');
-console.log('  Files:');
-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(`  ${WHITE}${BOLD}Auto-handoff:${NC} ${DIM}beta — disabled by default${NC}`);
+console.log(`  ${GRAY}Run ${CYAN}/auto-handoff${GRAY} inside Claude Code to enable${NC}`);
 console.log('');
-console.log(`  ${YELLOW}Start Claude Code and use /resume to begin.${NC}`);
+console.log(`  ${DIM}Start Claude Code and use ${WHITE}/resume${DIM} to begin.${NC}`);
 console.log('');

package/commands/auto-handoff.md

@@ -6,9 +6,9 @@ Toggle the automatic handoff context monitor on/off, configure threshold, and se
 
 ### Step 1: Check current state
 
-Check if `.claude/hooks/.auto-handoff-disabled` exists:
-- If exists → currently DISABLED
-- If not exists → currently ENABLED
+Check if `.claude/hooks/.auto-handoff-enabled` exists:
+- If exists → currently ENABLED
+- If not exists → currently DISABLED (default)
 
 Also read from `.claude/hooks/context-monitor.sh`:
 - `THRESHOLD_PERCENT` value (the default in `THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-XX}`)
@@ -30,7 +30,9 @@ Use AskUserQuestion:
 ### Step 3: Execute
 
 #### Toggle (Ativar/Desativar):
-- Create or delete `.claude/hooks/.auto-handoff-disabled`
+- Ativar: create `.claude/hooks/.auto-handoff-enabled`
+- Desativar: delete `.claude/hooks/.auto-handoff-enabled`
+- Also delete legacy `.claude/hooks/.auto-handoff-disabled` if it exists
 
 #### Ajustar threshold:
 Ask with AskUserQuestion:
@@ -52,7 +54,7 @@ Ask with AskUserQuestion:
 - 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`
+Run both "Alterar plano" and "Ajustar threshold" flows above, then create `.claude/hooks/.auto-handoff-enabled`
 
 ### Step 4: Confirm
 

package/hooks/context-monitor.sh

@@ -3,9 +3,9 @@
 # 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
+# Auto-handoff is opt-in: only runs if explicitly enabled
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-if [ -f "$SCRIPT_DIR/.auto-handoff-disabled" ]; then
+if [ ! -f "$SCRIPT_DIR/.auto-handoff-enabled" ]; then
   exit 0
 fi
 

package/install.sh

@@ -1,18 +1,21 @@
 #!/bin/bash
-# claude-code-handoff — Session continuity for Claude Code
-# Install: curl -fsSL https://raw.githubusercontent.com/eximIA-Ventures/claude-code-handoff/main/install.sh | bash
-#
-# Or clone and run:
-#   git clone https://github.com/eximIA-Ventures/claude-code-handoff.git /tmp/claude-code-handoff
-#   cd /your/project && /tmp/claude-code-handoff/install.sh
+# ═══════════════════════════════════════════════════════
+#  claude-code-handoff — Installer
+#  Usage: curl -fsSL https://raw.githubusercontent.com/eximIA-Ventures/claude-code-handoff/main/install.sh | bash
+# ═══════════════════════════════════════════════════════
 
 set -e
 
-# Colors
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-CYAN='\033[0;36m'
-NC='\033[0m'
+# Colors (RGB)
+AMBER='\033[38;2;245;158;11m'
+GREEN='\033[38;2;16;185;129m'
+RED='\033[38;2;239;68;68m'
+CYAN='\033[38;2;34;211;238m'
+WHITE='\033[37m'
+GRAY='\033[90m'
+BOLD='\033[1m'
+DIM='\033[2m'
+RESET='\033[0m'
 
 REPO="eximIA-Ventures/claude-code-handoff"
 BRANCH="main"
@@ -20,13 +23,19 @@ RAW_BASE="https://raw.githubusercontent.com/$REPO/$BRANCH"
 PROJECT_DIR="$(pwd)"
 CLAUDE_DIR="$PROJECT_DIR/.claude"
 
+ok()   { echo -e "  ${GREEN}✓${RESET} $1"; }
+fail() { echo -e "  ${RED}✗${RESET} $1"; }
+info() { echo -e "  ${GRAY}$1${RESET}"; }
+head() { echo -e "\n  ${AMBER}${BOLD}$1${RESET}"; }
+
+# ─── Banner ───────────────────────────────────────────
 echo ""
-echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-echo -e "${CYAN}  claude-code-handoff — Session Continuity${NC}"
-echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-echo ""
-echo -e "  Project: ${GREEN}$PROJECT_DIR${NC}"
+echo -e "  ${AMBER}${BOLD}┌──────────────────────────────────────┐${RESET}"
+echo -e "  ${AMBER}${BOLD}│${RESET}   ${WHITE}${BOLD}claude-code-handoff${RESET}  ${DIM}v1.9${RESET}        ${AMBER}${BOLD}│${RESET}"
+echo -e "  ${AMBER}${BOLD}│${RESET}   ${GRAY}Session Continuity for Claude Code${RESET}  ${AMBER}${BOLD}│${RESET}"
+echo -e "  ${AMBER}${BOLD}└──────────────────────────────────────┘${RESET}"
 echo ""
+info "Project: ${WHITE}$PROJECT_DIR${RESET}"
 
 # Detect if running from cloned repo or via curl
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}" 2>/dev/null)" 2>/dev/null && pwd 2>/dev/null || echo "")"
@@ -34,49 +43,61 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}" 2>/dev/null)" 2>/dev/null && pwd
 download_file() {
   local src="$1"
   local dst="$2"
-
-  # If running from cloned repo, copy locally
   if [ -n "$SCRIPT_DIR" ] && [ -f "$SCRIPT_DIR/$src" ]; then
     cp "$SCRIPT_DIR/$src" "$dst"
   else
-    # Download from GitHub
     curl -fsSL "$RAW_BASE/$src" -o "$dst"
   fi
 }
 
-# 1. Create directories
-echo -e "  ${YELLOW}[1/10]${NC} Creating directories..."
+# ─── Pre-flight ───────────────────────────────────────
+head "Pre-flight"
+
+# Detect reinstall
+IS_REINSTALL=false
+SAVED_THRESHOLD=""
+SAVED_MAX_CONTEXT=""
+if [ -f "$CLAUDE_DIR/hooks/context-monitor.sh" ]; then
+  IS_REINSTALL=true
+  SAVED_THRESHOLD=$(grep -oP 'CLAUDE_CONTEXT_THRESHOLD:-\K[0-9]+' "$CLAUDE_DIR/hooks/context-monitor.sh" 2>/dev/null || echo "")
+  SAVED_MAX_CONTEXT=$(grep -oP 'CLAUDE_MAX_CONTEXT:-\K[0-9]+' "$CLAUDE_DIR/hooks/context-monitor.sh" 2>/dev/null || echo "")
+fi
+
+if [ "$IS_REINSTALL" = true ]; then
+  info "Existing installation found. Upgrading..."
+else
+  ok "Fresh install"
+fi
+
+# ─── Directories ──────────────────────────────────────
+head "Creating directories"
+
 mkdir -p "$CLAUDE_DIR/commands"
 mkdir -p "$CLAUDE_DIR/rules"
 mkdir -p "$CLAUDE_DIR/hooks"
 mkdir -p "$CLAUDE_DIR/handoffs/archive"
+ok "Directory structure created"
+
+# ─── Commands ─────────────────────────────────────────
+head "Installing commands"
 
-# 2. Download/copy 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"
+ok "6 slash commands installed"
+
+# ─── Rules ────────────────────────────────────────────
+head "Installing rules"
 
-# 3. Download/copy 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"
+ok "Behavioral rules installed"
 
-# 4. Install hooks (auto-handoff context monitor)
-echo -e "  ${YELLOW}[4/10]${NC} Installing hooks..."
-
-# Detect reinstall: save user's custom settings before overwriting
-IS_REINSTALL=false
-SAVED_THRESHOLD=""
-SAVED_MAX_CONTEXT=""
-if [ -f "$CLAUDE_DIR/hooks/context-monitor.sh" ]; then
-  IS_REINSTALL=true
-  SAVED_THRESHOLD=$(grep -oP 'CLAUDE_CONTEXT_THRESHOLD:-\K[0-9]+' "$CLAUDE_DIR/hooks/context-monitor.sh" 2>/dev/null || echo "")
-  SAVED_MAX_CONTEXT=$(grep -oP 'CLAUDE_MAX_CONTEXT:-\K[0-9]+' "$CLAUDE_DIR/hooks/context-monitor.sh" 2>/dev/null || echo "")
-fi
+# ─── Hooks ────────────────────────────────────────────
+head "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"
@@ -84,30 +105,28 @@ chmod +x "$CLAUDE_DIR/hooks/context-monitor.sh"
 chmod +x "$CLAUDE_DIR/hooks/session-cleanup.sh"
 
 if [ "$IS_REINSTALL" = true ]; then
-  # Restore user's custom settings
   if [ -n "$SAVED_THRESHOLD" ] && [ "$SAVED_THRESHOLD" != "90" ]; then
     sed -i.bak "s/CLAUDE_CONTEXT_THRESHOLD:-90/CLAUDE_CONTEXT_THRESHOLD:-${SAVED_THRESHOLD}/" "$CLAUDE_DIR/hooks/context-monitor.sh"
     rm -f "$CLAUDE_DIR/hooks/context-monitor.sh.bak"
-    echo -e "    Preserved threshold: ${CYAN}${SAVED_THRESHOLD}%${NC}"
+    ok "Preserved threshold: ${CYAN}${SAVED_THRESHOLD}%${RESET}"
   fi
   if [ -n "$SAVED_MAX_CONTEXT" ] && [ "$SAVED_MAX_CONTEXT" != "200000" ]; then
     sed -i.bak "s/CLAUDE_MAX_CONTEXT:-200000/CLAUDE_MAX_CONTEXT:-${SAVED_MAX_CONTEXT}/" "$CLAUDE_DIR/hooks/context-monitor.sh"
     rm -f "$CLAUDE_DIR/hooks/context-monitor.sh.bak"
-    echo -e "    Preserved max context: ${CYAN}${SAVED_MAX_CONTEXT} tokens${NC}"
+    ok "Preserved max context: ${CYAN}${SAVED_MAX_CONTEXT} tokens${RESET}"
   fi
-  # Don't touch .auto-handoff-disabled — preserve user's on/off choice
-else
-  # Fresh install: auto-handoff disabled by default (beta feature)
-  touch "$CLAUDE_DIR/hooks/.auto-handoff-disabled"
 fi
 
-# 5. Configure hooks in settings.json
-echo -e "  ${YELLOW}[5/10]${NC} Configuring hooks in settings.json..."
+# Clean up legacy disabled flag
+rm -f "$CLAUDE_DIR/hooks/.auto-handoff-disabled"
+ok "Context monitor + session cleanup hooks"
+
+# ─── Settings ─────────────────────────────────────────
+head "Configuring 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": {
@@ -116,22 +135,22 @@ if [ -f "$SETTINGS_FILE" ]; then
         }
       }'
       jq --argjson hooks "$(echo "$HOOKS_JSON" | jq '.hooks')" '. + {hooks: $hooks}' "$SETTINGS_FILE" > "${SETTINGS_FILE}.tmp" && mv "${SETTINGS_FILE}.tmp" "$SETTINGS_FILE"
+      ok "Hooks added to existing settings.json"
     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'
+      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\"",
+            "command": "\"\$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh\"",
             "timeout": 10
           }
         ]
@@ -142,7 +161,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
           }
         ]
@@ -151,21 +170,17 @@ if [ -f "$SETTINGS_FILE" ]; then
   }
 }
 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
+        ok "Hooks added (preserved language setting)"
+      else
+        cat > "$SETTINGS_FILE" << 'SETTINGSEOF'
 {
-  ${LANG_SETTING},
   "hooks": {
     "Stop": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "\"\$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh\"",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/context-monitor.sh\"",
             "timeout": 10
           }
         ]
@@ -176,7 +191,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
           }
         ]
@@ -185,11 +200,13 @@ SETTINGSEOF
   }
 }
 SETTINGSEOF
+        ok "Hooks config written"
       fi
     fi
+  else
+    ok "Hooks already configured"
   fi
 else
-  # Create new settings.json with hooks
   cat > "$SETTINGS_FILE" << 'SETTINGSEOF'
 {
   "hooks": {
@@ -218,11 +235,13 @@ else
   }
 }
 SETTINGSEOF
+  ok "settings.json created with hooks"
 fi
 
-# 6. Create initial _active.md if not exists
+# ─── Handoff ──────────────────────────────────────────
+head "Setting up handoff storage"
+
 if [ ! -f "$CLAUDE_DIR/handoffs/_active.md" ]; then
-  echo -e "  ${YELLOW}[6/10]${NC} Creating initial handoff..."
   cat > "$CLAUDE_DIR/handoffs/_active.md" << 'HANDOFF'
 # Session Handoff
 
@@ -249,33 +268,34 @@ if [ ! -f "$CLAUDE_DIR/handoffs/_active.md" ]; then
 ## Decisions Registry
 (none)
 HANDOFF
+  ok "Initial handoff template created"
 else
-  echo -e "  ${YELLOW}[6/10]${NC} Handoff already exists, keeping it"
+  ok "Existing handoff preserved"
 fi
 
-# 7. Add to .gitignore
-echo -e "  ${YELLOW}[7/10]${NC} Updating .gitignore..."
+# ─── Gitignore ────────────────────────────────────────
+head "Updating .gitignore"
+
 GITIGNORE="$PROJECT_DIR/.gitignore"
 if [ -f "$GITIGNORE" ]; then
   if ! grep -q ".claude/handoffs/" "$GITIGNORE" 2>/dev/null; then
     echo "" >> "$GITIGNORE"
     echo "# claude-code-handoff (personal session state)" >> "$GITIGNORE"
     echo ".claude/handoffs/" >> "$GITIGNORE"
+    ok "Added .claude/handoffs/ to .gitignore"
+  else
+    ok "Already in .gitignore"
   fi
 else
   echo "# claude-code-handoff (personal session state)" > "$GITIGNORE"
   echo ".claude/handoffs/" >> "$GITIGNORE"
+  ok ".gitignore created"
 fi
 
-# 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)
-
-At the START of every session, read `.claude/handoffs/_active.md` to recover context from prior sessions.
-During work, update the handoff proactively after significant milestones.
-Use `/handoff` before `/clear`. Use `/resume` to pick up. Use `/switch-context <topic>` to switch workstreams.'
+# ─── CLAUDE.md ────────────────────────────────────────
+head "Updating CLAUDE.md"
 
+CLAUDE_MD="$CLAUDE_DIR/CLAUDE.md"
 if [ -f "$CLAUDE_MD" ]; then
   if ! grep -q "Session Continuity" "$CLAUDE_MD" 2>/dev/null; then
     TEMP_FILE=$(mktemp)
@@ -295,6 +315,9 @@ if [ -f "$CLAUDE_MD" ]; then
       { print }
     ' "$CLAUDE_MD" > "$TEMP_FILE"
     mv "$TEMP_FILE" "$CLAUDE_MD"
+    ok "Session Continuity section added"
+  else
+    ok "Session Continuity already present"
   fi
 else
   cat > "$CLAUDE_MD" << 'CLAUDEMD'
@@ -306,10 +329,24 @@ At the START of every session, read `.claude/handoffs/_active.md` to recover con
 During work, update the handoff proactively after significant milestones.
 Use `/handoff` before `/clear`. Use `/resume` to pick up. Use `/switch-context <topic>` to switch workstreams.
 CLAUDEMD
+  ok "CLAUDE.md created"
 fi
 
-# 9. Summary
-echo -e "  ${YELLOW}[9/10]${NC} Verifying installation..."
+# ─── Legacy cleanup ──────────────────────────────────
+CLEANED=0
+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))
+  fi
+done
+if [ "$CLEANED" -gt 0 ]; then
+  info "Removed $CLEANED legacy command(s)"
+fi
+
+# ─── Verify ───────────────────────────────────────────
+head "Verifying"
+
 INSTALLED=0
 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))
@@ -318,31 +355,28 @@ 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}[10/10]${NC} Done!"
-echo ""
 if [ "$INSTALLED" -eq 6 ] && [ "$HOOKS_OK" -eq 2 ]; then
-  echo -e "${GREEN}  Installed successfully! ($INSTALLED/6 commands, $HOOKS_OK/2 hooks)${NC}"
+  ok "${INSTALLED}/6 commands, ${HOOKS_OK}/2 hooks"
 else
-  echo -e "${YELLOW}  Partial install: $INSTALLED/6 commands, $HOOKS_OK/2 hooks${NC}"
+  fail "Partial: ${INSTALLED}/6 commands, ${HOOKS_OK}/2 hooks"
 fi
+
+# ─── Done ─────────────────────────────────────────────
 echo ""
-echo -e "  Commands available:"
-echo -e "    ${CYAN}/handoff${NC}              Auto-save session (no wizard)"
-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 -e "  ${AMBER}${BOLD}════════════════════════════════════════${RESET}"
+echo -e "  ${GREEN}${BOLD}  Installed successfully!${RESET}"
+echo -e "  ${AMBER}${BOLD}════════════════════════════════════════${RESET}"
 echo ""
-echo -e "  Auto-handoff: ${YELLOW}(beta — disabled by default)${NC}"
-echo -e "    Use ${CYAN}/auto-handoff${NC} to enable and configure threshold"
+echo -e "  ${WHITE}${BOLD}Commands:${RESET}"
+echo -e "    ${CYAN}/handoff${RESET}            ${GRAY}Auto-save session${RESET}"
+echo -e "    ${CYAN}/resume${RESET}             ${GRAY}Resume with wizard${RESET}"
+echo -e "    ${CYAN}/save-handoff${RESET}       ${GRAY}Save with options${RESET}"
+echo -e "    ${CYAN}/switch-context${RESET}     ${GRAY}Switch workstream${RESET}"
+echo -e "    ${CYAN}/delete-handoff${RESET}     ${GRAY}Delete handoff(s)${RESET}"
+echo -e "    ${CYAN}/auto-handoff${RESET}       ${GRAY}Toggle auto-handoff${RESET}"
 echo ""
-echo -e "  Files:"
-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 -e "  ${WHITE}${BOLD}Auto-handoff:${RESET} ${DIM}beta — disabled by default${RESET}"
+echo -e "  ${GRAY}Run ${CYAN}/auto-handoff${GRAY} inside Claude Code to enable${RESET}"
 echo ""
-echo -e "  ${YELLOW}Start Claude Code and use /resume to begin.${NC}"
+echo -e "  ${DIM}Start Claude Code and use ${WHITE}/resume${DIM} to begin.${RESET}"
 echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-handoff",
-  "version": "1.8.1",
+  "version": "2.0.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"

package/uninstall.sh

@@ -50,6 +50,7 @@ rm -f "$CLAUDE_DIR/rules/auto-handoff.md"
 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-enabled"
 rm -f "$CLAUDE_DIR/hooks/.auto-handoff-disabled"
 rmdir "$CLAUDE_DIR/hooks" 2>/dev/null || true