title: Session Handoff slug: session-handoff category: workflow-pattern status: proven difficulty: intermediate tags: [continuity, context, sessions, multi-session, handoff] prerequisites: [basic-cli-usage, basic-git] estimated_time: 10min to learn, ongoing practice cost_per_use: "$0.02-$0.10 per handoff"
Session Handoff
Problem
CLI agent sessions are stateless — each new session starts with zero memory of what happened before. When you resume work the next day, the new agent instance does not know what was completed, what was attempted and failed, or what decisions were made. You waste time and tokens re-explaining context, and the agent may redo work or contradict previous decisions.
Solution
End every non-trivial session by writing a structured handoff artifact — a summary commit message, a TODO file, or a status document — that gives the next session complete context to continue seamlessly.
Step-by-Step
- Before ending a session: Ask the agent to summarize the current state.
- Capture: Write the summary to a known location (commit message, TODO.md, or .session-state file).
- Include key details: What was done, what is in progress, what is blocked, what decisions were made and why.
- Next session: Start by pointing the agent at the handoff artifact.
When to Use
- Multi-day tasks that span multiple sessions
- Handing off work between team members using shared agents
- Before taking a break from a complex task
- Any time you think "I need to remember where I left off"
- Before switching between different tasks in the same repo
When NOT to Use
- Single-session tasks that complete fully
- Throwaway exploratory work
- When the git log already tells the full story
Example: Claude Code
# End-of-session: generate handoff summary
claude -p "We're ending this session. Write a handoff summary to \
.claude/session-handoff.md with the following sections:
1. Completed: what was finished this session
2. In Progress: what is partially done (include file paths and line numbers)
3. Blocked: anything that needs human input or external action
4. Decisions: key decisions made and their rationale
5. Next Steps: ordered list of what to do next
6. Gotchas: anything surprising or tricky discovered"
# Commit the handoff
git add .claude/session-handoff.md
git commit -m "session: end-of-day handoff — auth refactor 60% complete
Completed: middleware refactor, token validation rewrite.
In progress: session management (src/auth/sessions.ts half done).
Next: finish sessions.ts, then update integration tests.
Blocked: need decision on Redis vs Postgres for session store."
# Start-of-session: load context from handoff
claude -p "Read .claude/session-handoff.md to understand where we left off. \
Summarize the current state and confirm what you'll work on next. \
Do not start coding until I confirm the plan."
# Alternative: use a TODO file as the living handoff doc
claude -p "Update TODO.md with the current status of all tasks. \
Mark completed items with [x]. Add notes on anything tricky."
# Team handoff via commit message
git log --format="%h %s" -5
# a1b2c3d session: auth refactor progress — see commit body for details
git log -1 --format="%B" a1b2c3d
# Shows the full handoff summary in the commit body
Example: Codex CLI
# End-of-session handoff
codex -q "Write a session handoff to .session-state.md covering:
completed work, in-progress items, decisions made, and next steps."
git add .session-state.md && git commit -m "session: handoff for billing feature"
# Next session start
codex -q "Read .session-state.md. Summarize where we left off and \
what to work on next."
Cost Estimate
| Activity | Typical Cost |
|---|---|
| Generate handoff | ~$0.02-$0.08 |
| Load handoff | ~$0.01-$0.03 |
| Per transition | ~$0.03-$0.10 |
Minimal cost that prevents expensive context re-discovery (which can cost $0.20-$0.50 in wasted exploration).
Maturity Notes
Status: Proven. This pattern addresses one of the most common pain points with CLI agents — session discontinuity. The structured format matters: free-form summaries tend to miss critical details. The six-section template (Completed, In Progress, Blocked, Decisions, Next Steps, Gotchas) covers the information a new session actually needs. Some teams automate this by adding a session-end hook or alias. Works especially well combined with Checkpoint Commits.