Session Handoff

Create handoff documents that enable fresh agents to continue work seamlessly.

Mode Selection

Creating a handoff? User wants to save state, pause work, or context is full. → Follow CREATE Workflow

Resuming from a handoff? User wants to continue previous work or load context. → Follow RESUME Workflow

Proactive suggestion? After substantial work (5+ file edits, complex debugging, major decisions):

"Consider creating a handoff document to preserve this context. Say 'create handoff' when ready."

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install session-handoff

CREATE Workflow

Step 1: Generate Scaffold

Run the smart scaffold script:

python scripts/create_handoff.py [task-slug]

For continuation handoffs (linking to previous work):

python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md

The script creates .claude/handoffs/ directory and generates a timestamped file with pre-filled metadata (timestamp, project path, git branch, recent commits, modified files).

Step 2: Complete the Document

Open the generated file and fill all [TODO: ...] sections. Prioritize:

1. •Current State Summary - What's happening right now
2. •Important Context - Critical info the next agent MUST know
3. •Immediate Next Steps - Clear, actionable first steps
4. •Decisions Made - Choices with rationale (not just outcomes)

See references/handoff-template.md for full structure.

Step 3: Validate

python scripts/validate_handoff.py <handoff-file>

Checks:

• •No [TODO: ...] placeholders remaining
• •Required sections present and populated
• •No potential secrets detected (API keys, passwords, tokens)
• •Referenced files exist
• •Quality score (0-100)

Do not finalize handoffs with secrets detected or score below 70.

Step 4: Confirm

Report to user:

• •Handoff file location
• •Validation score and warnings
• •Summary of captured context
• •First action item for next session

RESUME Workflow

Step 1: Find Handoffs

python scripts/list_handoffs.py

Step 2: Check Staleness

python scripts/check_staleness.py <handoff-file>

Staleness levels:

• •FRESH: Safe to resume
• •SLIGHTLY_STALE: Review changes first
• •STALE: Verify context carefully
• •VERY_STALE: Consider creating fresh handoff

Step 3: Load and Verify

Read the handoff document completely. If part of a chain, also read the previous handoff.

Follow references/resume-checklist.md:

1. •Verify project directory and git branch match
2. •Check if blockers resolved
3. •Validate assumptions still hold
4. •Review modified files for conflicts

Step 4: Begin Work

Start with "Immediate Next Steps" item #1.

Reference as you work:

• •"Critical Files" for important locations
• •"Key Patterns Discovered" for conventions
• •"Potential Gotchas" to avoid known issues

Handoff Chaining

For long-running projects, chain handoffs to maintain context lineage:

handoff-1.md (initial work)
    ↓
handoff-2.md --continues-from handoff-1.md
    ↓
handoff-3.md --continues-from handoff-2.md

When resuming from a chain, read the most recent handoff first, then reference predecessors as needed.

Storage

Location: .claude/handoffs/ Naming: YYYY-MM-DD-HHMMSS-[slug].md

Quality Criteria

Good handoffs have:

• •Zero ambiguity about current state
• •Clear, numbered next steps
• •Rationale for decisions (not just outcomes)
• •File paths with line numbers where relevant
• •No secrets or credentials

NEVER

• •Include API keys, passwords, tokens, or credentials
• •Leave TODO placeholders in finalized handoffs
• •Skip the validation step
• •Create handoffs without the Important Context section
• •Finalize handoffs with quality score below 70