claude-code-handoff 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hugo Capitelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# claude-code-handoff
+
+Session continuity for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Pick up exactly where you left off — across `/clear`, crashes, or context switches.
+
+## What it does
+
+Adds 4 slash commands to any Claude Code project:
+
+| Command | Description |
+|---------|-------------|
+| `/handoff` | Auto-save session state (no wizard, just save and go) |
+| `/resume` | Resume from a saved session (interactive wizard) |
+| `/save-handoff` | Save session state with options (interactive wizard) |
+| `/switch-context <topic>` | Switch between parallel workstreams |
+
+Session state is stored in `.claude/handoffs/` (gitignored by default) so each developer keeps their own context.
+
+## Install
+
+### Option A: npx (recommended)
+
+```bash
+cd your-project
+npx claude-code-handoff
+```
+
+### Option B: curl
+
+```bash
+cd your-project
+curl -fsSL https://raw.githubusercontent.com/hugocapitelli/claude-code-handoff/main/install.sh | bash
+```
+
+### Option C: clone & run
+
+```bash
+git clone https://github.com/hugocapitelli/claude-code-handoff.git /tmp/claude-code-handoff
+cd your-project
+/tmp/claude-code-handoff/install.sh
+```
+
+## What gets installed
+
+```
+your-project/
+└── .claude/
+    ├── commands/
+    │   ├── handoff.md            # /handoff command (auto-save)
+    │   ├── resume.md             # /resume command
+    │   ├── save-handoff.md       # /save-handoff command
+    │   └── switch-context.md     # /switch-context command
+    ├── rules/
+    │   └── session-continuity.md # Auto-loaded rules for Claude
+    └── handoffs/                 # Session state (gitignored)
+        ├── _active.md            # Current workstream
+        └── archive/              # Paused workstreams
+```
+
+The installer also:
+- Adds `.claude/handoffs/` to `.gitignore`
+- Adds a `Session Continuity` section to `.claude/CLAUDE.md` (creates one if missing)
+
+## Usage
+
+### Quick save before clearing
+
+```
+> /handoff
+# Claude auto-saves current context to .claude/handoffs/_active.md
+> /clear
+```
+
+### Save with options
+
+```
+> /save-handoff
+# Interactive wizard: update active, save as new context, or replace
+```
+
+### Resume next session
+
+```
+> /resume
+# Interactive wizard shows available sessions
+# Select one → Claude loads full context and shows next steps
+```
+
+### Switch workstreams
+
+```
+> /switch-context auth-refactor
+# Archives current session, loads auth-refactor context
+```
+
+## How it works
+
+The handoff file (`.claude/handoffs/_active.md`) captures:
+
+- **Active Workstream** — what you're working on
+- **Active Agent(s)** — which agents/personas are active
+- **What Was Done** — session-by-session log of completed work
+- **What's Next** — prioritized pending items
+- **Key Files** — important files for context reload
+- **Decisions Registry** — architectural decisions made
+
+When you `/resume`, Claude reads this file and presents a summary so you can continue exactly where you left off.
+
+The `_active.md` file acts like `HEAD` in git — it points to your current workstream. The `archive/` folder holds paused workstreams you can switch to anytime with `/switch-context`.
+
+## Uninstall
+
+```bash
+cd your-project
+curl -fsSL https://raw.githubusercontent.com/hugocapitelli/claude-code-handoff/main/uninstall.sh | bash
+```
+
+Or manually remove:
+```bash
+rm -rf .claude/commands/handoff.md .claude/commands/resume.md .claude/commands/save-handoff.md .claude/commands/switch-context.md
+rm -rf .claude/rules/session-continuity.md
+rm -rf .claude/handoffs/
+```
+
+## Requirements
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed
+- A project directory with (or without) an existing `.claude/` folder
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const NC = '\x1b[0m';
+
+const PROJECT_DIR = process.cwd();
+const CLAUDE_DIR = path.join(PROJECT_DIR, '.claude');
+const SCRIPT_DIR = __dirname;
+
+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('');
+
+// Helper
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function copyFile(src, dst) {
+  const srcPath = path.join(SCRIPT_DIR, src);
+  if (fs.existsSync(srcPath)) {
+    fs.copyFileSync(srcPath, dst);
+  } else {
+    console.error(`  Error: ${src} not found in package`);
+    process.exit(1);
+  }
+}
+
+// 1. Create directories
+console.log(`  ${YELLOW}[1/7]${NC} Creating directories...`);
+ensureDir(path.join(CLAUDE_DIR, 'commands'));
+ensureDir(path.join(CLAUDE_DIR, 'rules'));
+ensureDir(path.join(CLAUDE_DIR, 'handoffs', 'archive'));
+
+// 2. Copy commands
+console.log(`  ${YELLOW}[2/7]${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'));
+
+// 3. Copy rules
+console.log(`  ${YELLOW}[3/7]${NC} Installing rules...`);
+copyFile('rules/session-continuity.md', path.join(CLAUDE_DIR, 'rules', 'session-continuity.md'));
+
+// 4. Create initial _active.md
+const activePath = path.join(CLAUDE_DIR, 'handoffs', '_active.md');
+if (!fs.existsSync(activePath)) {
+  console.log(`  ${YELLOW}[4/7]${NC} Creating initial handoff...`);
+  fs.writeFileSync(activePath, `# Session Handoff
+
+> No active session yet. Use \`/handoff\` or \`/save-handoff\` to save your first session state.
+
+## Last Updated
+(not started)
+
+## Active Workstream
+(none)
+
+## Active Agent(s)
+(none)
+
+## What Was Done
+(nothing yet)
+
+## What's Next
+(define your first task)
+
+## Key Files
+(none)
+
+## Decisions Registry
+(none)
+`);
+} else {
+  console.log(`  ${YELLOW}[4/7]${NC} Handoff already exists, keeping it`);
+}
+
+// 5. Update .gitignore
+console.log(`  ${YELLOW}[5/7]${NC} 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');
+  }
+} else {
+  fs.writeFileSync(gitignorePath, '# claude-code-handoff (personal session state)\n.claude/handoffs/\n');
+}
+
+// 6. Update CLAUDE.md
+console.log(`  ${YELLOW}[6/7]${NC} Updating CLAUDE.md...`);
+const claudeMdPath = path.join(CLAUDE_DIR, 'CLAUDE.md');
+const continuityBlock = `## 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.`;
+
+if (fs.existsSync(claudeMdPath)) {
+  const content = fs.readFileSync(claudeMdPath, 'utf-8');
+  if (!content.includes('Session Continuity')) {
+    const lines = content.split('\n');
+    const firstHeadingIdx = lines.findIndex(l => l.startsWith('# '));
+    if (firstHeadingIdx >= 0) {
+      lines.splice(firstHeadingIdx + 1, 0, '', continuityBlock, '');
+      fs.writeFileSync(claudeMdPath, lines.join('\n'));
+    } else {
+      fs.appendFileSync(claudeMdPath, '\n' + continuityBlock + '\n');
+    }
+  }
+} else {
+  fs.writeFileSync(claudeMdPath, `# Project Rules\n\n${continuityBlock}\n`);
+}
+
+// 7. Verify
+console.log(`  ${YELLOW}[7/7]${NC} Verifying installation...`);
+let installed = 0;
+for (const f of ['resume.md', 'save-handoff.md', 'switch-context.md', 'handoff.md']) {
+  if (fs.existsSync(path.join(CLAUDE_DIR, 'commands', f))) installed++;
+}
+
+console.log('');
+if (installed === 4) {
+  console.log(`${GREEN}  Installed successfully! (${installed}/4 commands)${NC}`);
+} else {
+  console.log(`${YELLOW}  Partial install: ${installed}/4 commands${NC}`);
+}
+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('');
+console.log('  Files:');
+console.log('    .claude/commands/     4 command files');
+console.log('    .claude/rules/        session-continuity.md');
+console.log('    .claude/handoffs/     session state (gitignored)');
+console.log('');
+console.log(`  ${YELLOW}Start Claude Code and use /resume to begin.${NC}`);
+console.log('');

package/commands/handoff.md

@@ -0,0 +1,118 @@
+# Auto Handoff
+
+Automatically save session state and prepare for context clear. No wizard — just save and go.
+
+## Instructions
+
+### Step 1: Analyze conversation
+
+Scan the full conversation and extract:
+- **Workstream name**: The project/feature/topic being worked on
+- **Active Agent(s)**: Any agent personas active (e.g., @dev, @architect) or "none"
+- **What Was Done**: All concrete actions completed THIS session (files created/modified, decisions made, features implemented, bugs fixed)
+- **What's Next**: Unfinished work, pending items, logical next steps
+- **Key Files**: Every file that was created, modified, or is essential to resume
+- **Current Document**: The main file being worked on (if any)
+- **Decisions**: Any architectural or design decisions made
+
+Be thorough — this is the only record of the session.
+
+### Step 2: Determine save target
+
+1. Read `.claude/handoffs/_active.md` (if it exists)
+2. Check if it has real content (not the default placeholder)
+
+**If active handoff exists with content:**
+- Compare the active workstream name with what was worked on this session
+- If same workstream: **append** to existing handoff (preserve session history)
+- If different workstream: **archive** the old one, create new active
+
+**If no active handoff or placeholder only:**
+- Create new active handoff
+
+**If `$ARGUMENTS` is provided:**
+- Use it as the workstream name/slug
+- Save directly without comparison logic
+
+### Step 3: Write the handoff
+
+Ensure `.claude/handoffs/` and `.claude/handoffs/archive/` directories exist.
+
+**When appending** to an existing handoff:
+1. Read the current `_active.md`
+2. Add a new session entry under "## What Was Done" with current date
+3. Update "## What's Next" (replace with current pending items)
+4. Merge new files into "## Key Files" (don't duplicate)
+5. Append any new decisions to "## Decisions Registry"
+6. Update "## Last Updated"
+
+**When creating fresh:**
+Write `.claude/handoffs/_active.md` with this template:
+
+```markdown
+# Session Handoff
+
+> Updated automatically. Read this to resume work after /clear.
+
+## Last Updated
+[YYYY-MM-DD] — [brief description of session]
+
+## Active Workstream
+**[workstream name]** — [one-line description]
+
+## Active Agent(s)
+[agents or "none"]
+
+## Current Document
+[main file path or "none"]
+
+## What Was Done
+
+### Session 1 ([YYYY-MM-DD])
+- [concrete action 1]
+- [concrete action 2]
+- ...
+
+## What's Next
+1. [specific actionable item]
+2. [specific actionable item]
+...
+
+## Key Files
+| File | Purpose |
+|------|---------|
+| path/to/file | what it does |
+
+## Decisions Registry
+[decisions table or "(none)"]
+```
+
+### Step 4: Confirm and instruct
+
+Output exactly this:
+
+```
+## Handoff saved
+
+**Workstream:** [name]
+**File:** `.claude/handoffs/_active.md`
+**Recorded:** [count] actions done, [count] next steps
+
+You can now type `/clear` to free context.
+Then start a new session and use `/resume` to pick up where you left off.
+```
+
+## Design Rationale
+
+This command exists because:
+1. **No wizard friction** — `/save-handoff` has a wizard for choosing where to save. `/handoff` just saves and goes.
+2. **Context-aware** — it appends to the active handoff if the workstream matches, or creates a new one if it doesn't.
+3. **Pre-clear workflow** — the natural flow is: work → `/handoff` → `/clear` → `/resume`.
+
+## Important
+- Be THOROUGH — extract everything relevant from the conversation
+- Be PRECISE — file paths, specific changes, exact error messages
+- Be ACTIONABLE — next steps should be specific enough to execute cold
+- NEVER delete existing handoff data — always append or archive
+- Keep under 200 lines — summarize older sessions if handoff grows large
+- If conversation is very short or trivial, still save (even a one-liner is better than nothing)

package/commands/resume.md

@@ -0,0 +1,75 @@
+# Resume Session
+
+Resume work from a previous session using the handoff system.
+
+## Instructions
+
+### Step 1: Discover all handoffs
+
+1. Check if `.claude/handoffs/_active.md` exists and has content (not the default placeholder)
+2. List all `.md` files in `.claude/handoffs/archive/`
+3. For each file found, read the first 10 lines to extract: **Active Workstream**, **Last Updated**, and the first line of **What's Next**
+
+### Step 2: Present wizard
+
+Use the AskUserQuestion tool to present available handoffs as options.
+
+Build the options list:
+- If `_active.md` has content: add it as first option with label "(active) [workstream name]" and description showing last updated date + first pending item
+- For each file in `archive/`: add as option with label "[workstream name]" and description showing last updated date + first pending item
+- If NO handoffs exist at all, skip the wizard and tell the user: "No handoffs found. Use `/save-handoff` at the end of this session to create the first one."
+
+Question: "Which session do you want to resume?"
+Header: "Handoff"
+
+### Step 3: Load selected handoff
+
+Once the user selects, read the full handoff file and extract:
+- Active Workstream
+- Active Agent(s)
+- What Was Done (last session summary)
+- What's Next (pending items)
+- Key Files
+- Decisions Registry (if any)
+
+### Step 4: Refresh context
+
+If **Key Files** lists a main document (Current Document field), read the first 50 lines of it.
+
+### Step 5: Present context
+
+```
+## Resuming session
+
+**Workstream:** [name]
+**Agent(s):** [active agents]
+**Document:** [main file]
+**Last updated:** [date]
+
+### Last session summary
+[3-5 lines from What Was Done, focusing on the MOST RECENT session entry]
+
+### Next steps
+1. [item from What's Next]
+2. [item]
+...
+
+What would you like to do?
+```
+
+### Step 6: Wait
+
+Wait for user instruction before proceeding.
+
+## Shortcut
+
+If `$ARGUMENTS` is provided (e.g., `/resume auth-refactor`), skip the wizard:
+- Look for `.claude/handoffs/archive/$ARGUMENTS.md` first
+- If not found, check if `_active.md` workstream slug matches `$ARGUMENTS`
+- If still not found, show the wizard with a note: "Handoff '$ARGUMENTS' not found. Choose from available:"
+
+## Important
+- Do NOT activate any agent automatically — let the user decide
+- Do NOT start working — only present context and wait
+- If the handoff references an agent (e.g., @architect), mention it but don't activate
+- The wizard should clearly show which is the ACTIVE handoff vs archived ones

package/commands/save-handoff.md

@@ -0,0 +1,135 @@
+# Save Handoff
+
+Save the current session state for future resumption.
+
+## Instructions
+
+### Step 1: Analyze current session
+
+Before showing the wizard, analyze the current conversation and extract:
+- **Workstream name**: What project/feature/epic is being worked on
+- **Active Agent(s)**: Which agent personas are active
+- **What Was Done**: Concrete actions completed THIS session
+- **What's Next**: Specific pending items
+- **Key Files**: Files created, modified, or essential to read when resuming
+- **Decisions Registry**: Any decisions made with IDs
+
+### Step 2: Present wizard
+
+Use the AskUserQuestion tool to ask where to save.
+
+**Discover existing handoffs first:**
+1. Check if `.claude/handoffs/_active.md` exists and extract its workstream name
+2. List files in `.claude/handoffs/archive/` to show existing contexts
+
+**Present options:**
+
+Question: "Where should this session's handoff be saved?"
+Header: "Target"
+
+Options (build dynamically):
+1. **Label:** "Update active ([workstream name])" — **Description:** "Append this session to the current active handoff. Use when working on the same context."
+2. **Label:** "Save as new context" — **Description:** "Create a separate handoff. Use when working on something different from the active context."
+3. **Label:** "Replace active" — **Description:** "Discard the active handoff and create a new one with this session. Use when the active context is obsolete."
+
+If `_active.md` does NOT exist or is the default placeholder, show only:
+1. **Label:** "Create handoff" — **Description:** "Create the first handoff for this project."
+2. **Label:** "Create with specific name" — **Description:** "Create handoff with a custom name to organize by topic."
+
+### Step 3: Execute based on choice
+
+#### Choice: "Update active"
+1. Read `.claude/handoffs/_active.md`
+2. Append new session entry to "What Was Done" (preserve history)
+3. Update "What's Next", "Key Files", "Decisions Registry", "Last Updated"
+4. Write back to `.claude/handoffs/_active.md`
+
+#### Choice: "Save as new context"
+1. Ask the user for a name using AskUserQuestion:
+   - Question: "Context name (will be the filename)?"
+   - Header: "Name"
+   - Options: suggest 2-3 slugs based on what was discussed (e.g., "auth-refactor", "bugfix-login"), plus "Other" for custom input
+2. If `_active.md` has content, move it to `archive/{current-slug}.md` first
+3. Create new `.claude/handoffs/_active.md` with this session's data
+4. Also save a copy to `archive/{chosen-name}.md`
+
+#### Choice: "Replace active"
+1. If `_active.md` has content, move it to `archive/{current-slug}.md` (never lose data)
+2. Create fresh `.claude/handoffs/_active.md` with only this session's data
+
+#### Choice: "Create handoff" (first time)
+1. Create `.claude/handoffs/_active.md` with this session's data
+
+#### Choice: "Create with specific name" (first time)
+1. Ask for name (same as "Save as new context")
+2. Create `.claude/handoffs/_active.md` with this session's data
+3. Also save copy to `archive/{chosen-name}.md`
+
+### Step 4: Write the handoff
+
+Use this structure for the handoff content:
+
+```markdown
+# Session Handoff
+
+> Updated automatically. Read this to resume work after /clear.
+
+## Last Updated
+[current date and brief description]
+
+## Active Workstream
+[workstream name and brief context]
+
+## Active Agent(s)
+[agent names and roles]
+
+## Current Document
+[main file being worked on, if any]
+
+## What Was Done
+
+### Session [N] ([date])
+[bullet points of concrete actions — be specific, not vague]
+
+### Session [N-1] ([date])
+[preserve previous sessions — don't delete history]
+
+## What's Next
+1. [specific actionable item]
+2. [specific actionable item]
+...
+
+## Key Files
+| File | Purpose |
+|------|---------|
+| path/to/file | what it is |
+
+## Decisions Registry
+| # | Decision | Choice | Justification |
+|---|----------|--------|---------------|
+| D1 | ... | ... | ... |
+```
+
+### Step 5: Confirm
+
+```
+Handoff saved to [path]
+- [1-line summary of what was recorded]
+- Next steps: [count] pending items
+- Available contexts: [list of all handoff names]
+```
+
+## Shortcut
+
+If `$ARGUMENTS` is provided:
+- If it matches an existing archive name: update that specific archive file directly (skip wizard)
+- Otherwise: treat as the name for a new context (skip wizard, go to "Save as new context" flow)
+
+## Important
+- NEVER delete or overwrite without archiving first — always move to archive/
+- PRESERVE session history — append, don't replace
+- Be PRECISE — file paths, decision IDs, specific changes
+- Be ACTIONABLE — someone reading cold should know exactly what to do
+- Keep CONCISE — target <200 lines per handoff
+- If a handoff exceeds 300 lines, summarize older sessions into "Prior Sessions Summary"
+- Slug derivation: lowercase, trim, replace spaces/special chars with hyphens, max 40 chars

package/commands/switch-context.md

@@ -0,0 +1,65 @@
+# Switch Context
+
+Switch between workstreams by archiving the current handoff and loading another.
+
+## Instructions
+
+**Argument required:** `$ARGUMENTS` must contain the target workstream name (e.g., `auth-refactor`).
+
+If no argument provided, list available contexts and ask the user to choose:
+1. Read `.claude/handoffs/_active.md` and show its workstream name as "(active)"
+2. List all `.md` files in `.claude/handoffs/archive/` as available contexts
+3. Present as numbered list and wait for selection
+
+### Switch Flow
+
+1. **Read the current active handoff** at `.claude/handoffs/_active.md`
+   - Extract the workstream name from "## Active Workstream"
+   - Derive a slug from it (lowercase, spaces to hyphens, no special chars)
+   - Example: "Auth Refactor" → `auth-refactor`
+
+2. **Archive the current handoff:**
+   - Copy `.claude/handoffs/_active.md` → `.claude/handoffs/archive/{slug}.md`
+   - This preserves the current state before switching
+
+3. **Load the target handoff:**
+   - Look for `.claude/handoffs/archive/$ARGUMENTS.md`
+   - If found: copy it → `.claude/handoffs/_active.md` and delete the archive copy
+   - If NOT found: create a fresh `.claude/handoffs/_active.md` with the target name as Active Workstream (new context)
+
+4. **Present the switch result:**
+
+```
+## Context switched
+
+**From:** [previous workstream] → archived to `.claude/handoffs/archive/{slug}.md`
+**To:** [new workstream]
+
+### New context state
+[summary from the loaded handoff — What Was Done + What's Next]
+
+What would you like to do?
+```
+
+5. **Wait for user instruction.**
+
+## Examples
+
+```
+/switch-context auth-refactor
+→ Archives current handoff
+→ Loads auth-refactor handoff
+→ Shows auth-refactor context
+
+/switch-context new-feature-payments
+→ Archives current handoff
+→ No archive found for "new-feature-payments"
+→ Creates fresh handoff with that name
+→ Shows empty context, asks what to work on
+```
+
+## Important
+- ALWAYS archive before switching — never lose state
+- The archive acts as a "stack" of paused workstreams
+- Users can have unlimited archived contexts
+- Slug derivation: lowercase, trim, replace spaces/special chars with hyphens

package/install.sh

@@ -0,0 +1,178 @@
+#!/bin/bash
+# claude-code-handoff — Session continuity for Claude Code
+# Install: curl -fsSL https://raw.githubusercontent.com/hugocapitelli/claude-code-handoff/main/install.sh | bash
+#
+# Or clone and run:
+#   git clone https://github.com/hugocapitelli/claude-code-handoff.git /tmp/claude-code-handoff
+#   cd /your/project && /tmp/claude-code-handoff/install.sh
+
+set -e
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+REPO="hugocapitelli/claude-code-handoff"
+BRANCH="main"
+RAW_BASE="https://raw.githubusercontent.com/$REPO/$BRANCH"
+PROJECT_DIR="$(pwd)"
+CLAUDE_DIR="$PROJECT_DIR/.claude"
+
+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 ""
+
+# 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 "")"
+
+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/7]${NC} Creating directories..."
+mkdir -p "$CLAUDE_DIR/commands"
+mkdir -p "$CLAUDE_DIR/rules"
+mkdir -p "$CLAUDE_DIR/handoffs/archive"
+
+# 2. Download/copy commands
+echo -e "  ${YELLOW}[2/7]${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"
+
+# 3. Download/copy rules
+echo -e "  ${YELLOW}[3/7]${NC} Installing rules..."
+download_file "rules/session-continuity.md" "$CLAUDE_DIR/rules/session-continuity.md"
+
+# 4. Create initial _active.md if not exists
+if [ ! -f "$CLAUDE_DIR/handoffs/_active.md" ]; then
+  echo -e "  ${YELLOW}[4/7]${NC} Creating initial handoff..."
+  cat > "$CLAUDE_DIR/handoffs/_active.md" << 'HANDOFF'
+# Session Handoff
+
+> No active session yet. Use `/handoff` or `/save-handoff` to save your first session state.
+
+## Last Updated
+(not started)
+
+## Active Workstream
+(none)
+
+## Active Agent(s)
+(none)
+
+## What Was Done
+(nothing yet)
+
+## What's Next
+(define your first task)
+
+## Key Files
+(none)
+
+## Decisions Registry
+(none)
+HANDOFF
+else
+  echo -e "  ${YELLOW}[4/7]${NC} Handoff already exists, keeping it"
+fi
+
+# 5. Add to .gitignore
+echo -e "  ${YELLOW}[5/7]${NC} 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"
+  fi
+else
+  echo "# claude-code-handoff (personal session state)" > "$GITIGNORE"
+  echo ".claude/handoffs/" >> "$GITIGNORE"
+fi
+
+# 6. Add to CLAUDE.md
+echo -e "  ${YELLOW}[6/7]${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.'
+
+if [ -f "$CLAUDE_MD" ]; then
+  if ! grep -q "Session Continuity" "$CLAUDE_MD" 2>/dev/null; then
+    TEMP_FILE=$(mktemp)
+    awk '
+      /^# / && !done {
+        print
+        print ""
+        print "## Session Continuity (MANDATORY)"
+        print ""
+        print "At the START of every session, read `.claude/handoffs/_active.md` to recover context from prior sessions."
+        print "During work, update the handoff proactively after significant milestones."
+        print "Use `/handoff` before `/clear`. Use `/resume` to pick up. Use `/switch-context <topic>` to switch workstreams."
+        print ""
+        done=1
+        next
+      }
+      { print }
+    ' "$CLAUDE_MD" > "$TEMP_FILE"
+    mv "$TEMP_FILE" "$CLAUDE_MD"
+  fi
+else
+  cat > "$CLAUDE_MD" << 'CLAUDEMD'
+# Project Rules
+
+## 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.
+CLAUDEMD
+fi
+
+# 7. Summary
+echo -e "  ${YELLOW}[7/7]${NC} Verifying installation..."
+INSTALLED=0
+for f in resume.md save-handoff.md switch-context.md handoff.md; do
+  [ -f "$CLAUDE_DIR/commands/$f" ] && INSTALLED=$((INSTALLED + 1))
+done
+
+echo ""
+if [ "$INSTALLED" -eq 4 ]; then
+  echo -e "${GREEN}  Installed successfully! ($INSTALLED/4 commands)${NC}"
+else
+  echo -e "${YELLOW}  Partial install: $INSTALLED/4 commands${NC}"
+fi
+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 ""
+echo -e "  Files:"
+echo -e "    .claude/commands/     4 command files"
+echo -e "    .claude/rules/        session-continuity.md"
+echo -e "    .claude/handoffs/     session state (gitignored)"
+echo ""
+echo -e "  ${YELLOW}Start Claude Code and use /resume to begin.${NC}"
+echo ""

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "claude-code-handoff",
+  "version": "1.1.0",
+  "description": "Session continuity for Claude Code — 4 slash commands to save, resume, and switch workstreams across /clear",
+  "bin": {
+    "claude-code-handoff": "./cli.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "handoff",
+    "session",
+    "continuity",
+    "ai",
+    "context"
+  ],
+  "author": "Hugo Capitelli",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hugocapitelli/claude-code-handoff"
+  }
+}

package/rules/session-continuity.md

@@ -0,0 +1,27 @@
+---
+paths: **/*
+---
+
+# Session Continuity Rules
+
+## Handoff System
+
+This project uses a handoff system for session continuity. Handoff files are stored in `.claude/handoffs/`.
+
+### On Session Start
+- If `.claude/handoffs/_active.md` exists and has content, be aware of it but do NOT read it automatically unless the user invokes `/resume` or says "continue"/"resume"
+
+### During Work
+- After completing significant milestones (major edits, decisions made, features implemented), proactively update the handoff by writing to `.claude/handoffs/_active.md`
+- If the session has been going for a while and substantial work was done, remind the user: "Want me to save the handoff before continuing?"
+
+### Handoff Structure
+- `_active.md` — current active workstream (the ONE thing being worked on now)
+- `archive/` — paused or completed workstreams (switched via `/switch-context`)
+
+### Commands Available
+- `/resume` — resume from active handoff (interactive wizard)
+- `/resume <topic>` — resume from a specific archived handoff
+- `/save-handoff` — save current state (interactive wizard)
+- `/switch-context <topic>` — switch workstream (archives current, loads target)
+- `/handoff` — auto-save session state (no wizard, just save and go)

package/uninstall.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+# claude-code-handoff — Uninstall
+# Usage: curl -fsSL https://raw.githubusercontent.com/hugocapitelli/claude-code-handoff/main/uninstall.sh | bash
+
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+PROJECT_DIR="$(pwd)"
+CLAUDE_DIR="$PROJECT_DIR/.claude"
+
+echo ""
+echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${CYAN}  claude-code-handoff — Uninstall${NC}"
+echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo -e "  Project: ${GREEN}$PROJECT_DIR${NC}"
+echo ""
+
+if [ ! -d "$CLAUDE_DIR" ]; then
+  echo -e "  ${RED}No .claude/ directory found. Nothing to uninstall.${NC}"
+  exit 0
+fi
+
+# 1. Remove commands
+echo -e "  ${YELLOW}[1/4]${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"
+# 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..."
+rm -f "$CLAUDE_DIR/rules/session-continuity.md"
+
+# 3. 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)..."
+    rm -rf "$CLAUDE_DIR/handoffs"
+  else
+    echo -e "  ${YELLOW}[3/4]${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"
+fi
+
+# 4. Clean .gitignore
+echo -e "  ${YELLOW}[4/4]${NC} Cleaning .gitignore..."
+GITIGNORE="$PROJECT_DIR/.gitignore"
+if [ -f "$GITIGNORE" ]; then
+  # Remove the handoff lines
+  sed -i.bak '/# claude-code-handoff/d; /^\.claude\/handoffs\/$/d' "$GITIGNORE"
+  rm -f "$GITIGNORE.bak"
+  # Remove trailing blank lines
+  sed -i.bak -e :a -e '/^\n*$/{$d;N;ba' -e '}' "$GITIGNORE"
+  rm -f "$GITIGNORE.bak"
+fi
+
+# Clean up empty directories
+rmdir "$CLAUDE_DIR/commands" 2>/dev/null || true
+rmdir "$CLAUDE_DIR/rules" 2>/dev/null || true
+rmdir "$CLAUDE_DIR" 2>/dev/null || true
+
+echo ""
+echo -e "${GREEN}  Uninstalled successfully!${NC}"
+echo ""
+echo -e "  Note: Session Continuity section in CLAUDE.md was NOT removed."
+echo -e "  Edit .claude/CLAUDE.md manually if you want to remove it."
+echo ""