Runbook: Agent Handoff

Purpose: Transfer an in-progress task from one Claude Code session to another without losing context When to use: Session hitting context limits, switching machines, or resuming after a break Prerequisites: Active Claude Code session with work in progress Estimated time: 2-5 minutes

Steps

1. Capture current state

Check for active warp-drive session:

node ~/.claude/scripts/warp-drive/state-machine.js status "$(pwd)"

Expected output: JSON with phase, requirement, chunk, and metrics fields.

Decision point: If warp-drive is active, go to step 2. If not, go to step 3.

2. Record warp-drive state

The state file persists at .claude/.warp-drive-state.json. The new session will auto-resume from it.

Verify the state file is committed or tracked:

cat .claude/.warp-drive-state.json | jq '{phase, requirement, branch, chunk}'

Expected output: Current phase, issue number, branch name, and chunk progress.

Decision point: If phase is coding or testing with uncommitted changes, go to step 4. Otherwise go to step 5.

3. Check for uncommitted work (no warp-drive)

git status --short
git stash list

Expected output: List of modified/untracked files or stashed changes.

Decision point: If uncommitted changes exist, go to step 4. If clean, go to step 5.

4. Preserve uncommitted work

Option A — Stash (preferred for short breaks):

git stash push -m "handoff: $(date +%Y-%m-%d) - {brief description}"

Option B — WIP commit (preferred for long breaks or machine switch):

git add -A && git commit -m "WIP: {what was in progress}"

5. Record context for the new session

Check the GitHub issue for current status:

gh issue view {ISSUE_NUMBER}

Verify the branch exists on remote (if switching machines):

git push origin $(git branch --show-current)

6. Start new session

In the new Claude Code session:

/warp-drive

Warp-drive will detect the existing state file and resume from the recorded phase.

If no warp-drive: Tell the new session:

“I’m continuing work on #{ISSUE_NUMBER}. The branch is {branch-name}. Check git log --oneline -5 and git stash list for context.”

Troubleshooting

Symptom	Likely Cause	Fix
New session starts fresh instead of resuming	State file missing or stale PID	Check .claude/.warp-drive-state.json exists
“Active session exists” error on init	Previous session still running	Stop the other session or node ~/.claude/scripts/warp-drive/state-machine.js reset "$(pwd)"
Lost uncommitted changes	Forgot to stash/commit before switching	Check git reflog and git stash list

Escalation

If this runbook doesn’t resolve the issue:

1. Check the warp-drive state file manually: cat .claude/.warp-drive-state.json
2. Reset warp-drive and restart from the last committed chunk: node ~/.claude/scripts/warp-drive/state-machine.js reset "$(pwd)"