# Session Capture & Handoff ## Your Role You capture key decisions, open questions, and follow-ups from work sessions and write structured entries for cross-session continuity. ## Arguments - *(none)* — full capture (decisions + questions + follow-ups + context) - `quick` — abbreviated capture (decisions + follow-ups only, no context summary) - `project:name` — tag the entry with a specific project name ## Instructions ### Step 1: Identify Session Scope Review the conversation history and determine: - **Session topic(s):** What was worked on? (1-2 line summary) - **Project(s) touched:** Match against known projects - **Duration indicator:** Brief (< 10 exchanges), Medium (10-30), Extended (30+) ### Step 2: Extract Session Artifacts Scan the conversation for: **Decisions made** — things decided or confirmed: - Configuration changes, skill edits, policy updates - Approach selections ("we'll use method X instead of Y") - Commitments ("will send email to X by Friday") **Open questions** — unresolved items needing future attention: - Questions raised but not answered - Items deferred ("we'll handle that next time") - Blockers or dependencies on external input **Follow-ups** — concrete next steps: - Tasks for a future session - Things to check, test, or verify - People to contact or documents to review **Key artifacts** — files written or modified: - New files or config created - Documents drafted or edited - State changes (emails sent, reminders modified) ### Step 3: Write Session Entry Append to `~/Documents/session-log.md` (newest entries at top): ```markdown --- ## [YYYY-MM-DD HH:MM] — [Session topic summary] **Project(s):** [project names or "General"] **Duration:** [Brief/Medium/Extended] ### Decisions - [Decision 1] - [Decision 2] ### Open Questions - [Question 1] - [Question 2] ### Follow-ups - [ ] [Action item 1] - [ ] [Action item 2] ### Artifacts - [Created/Modified] `path/to/file` — [what changed] ### Context [2-4 sentences of key context for future session pickup] ``` If the file doesn't exist, create it with: ```markdown # Session Log *Auto-generated. Reverse chronological — newest entries at top.* ``` ### Step 3.5: Generate Handoff Note Write to `~/.claude/handoff.md` (overwrite previous): ```markdown # Handoff — [YYYY-MM-DD] ## Session Topic [1-line summary] ## Key Decisions - [Decision 1] ## Open Follow-ups - [ ] [Most important next step] ## Context for Next Session [1-2 sentences for seamless pickup] ``` ### Step 4: Display Summary ``` SESSION CAPTURED Topic: [summary] Decisions: [N] | Questions: [N] | Follow-ups: [N] | Artifacts: [N] Logged to: session-log.md ``` ### Step 5: Maintenance - Prune entries older than 60 days (archive or remove) ## Error Handling - **No substantive content:** Report "Nothing to capture — session was too brief." - **Write fails:** Display the entry in terminal for manual saving.

What This Does

Solves the "where did I leave off?" problem. At the end of any work session, Claude scans the conversation and extracts decisions, open questions, follow-ups, and artifacts into a structured log. It also writes a condensed handoff note so your next session starts with full context.

Quick Start

Step 1: Download the Template

Click Download above, then:

mv ~/Downloads/CLAUDE.md ~/Documents/

Step 2: Run Claude Code

At the end of any work session:

claude

Then: "Capture this session" or "Done"

What Gets Captured

Category	Examples
Decisions made	Config changes, approach selections, commitments
Open questions	Unresolved items, deferred decisions, external dependencies
Follow-ups	Tasks for next session, things to check/test, people to contact
Artifacts	Files created or modified, emails sent, state changes

Example Output

The session log entry looks like:

## 2026-02-27 14:30 — API Authentication Refactor

**Project:** Backend API
**Duration:** Extended

### Decisions
- Switched from API keys to OAuth 2.0 tokens
- Will use refresh token rotation with 24h expiry

### Open Questions
- Should we support both auth methods during migration?
- Need to check if mobile app handles token refresh

### Follow-ups
- [ ] Update API documentation with new auth flow
- [ ] Test refresh token rotation with the mobile team
- [ ] Draft migration guide for API consumers

### Artifacts
- [Modified] `src/auth/middleware.ts` — replaced API key validation
- [Created] `src/auth/oauth.ts` — new OAuth handler

### Context
Refactored auth to OAuth 2.0 for better security. Mobile team
needs to test token refresh — their current implementation may
not handle rotation. Migration period TBD.

The Handoff File

A condensed summary is written to ~/.claude/handoff.md so your next Claude Code session automatically knows what to pick up:

# Handoff — 2026-02-27

## Session Topic
API authentication refactor to OAuth 2.0

## Key Decisions
- OAuth 2.0 with refresh token rotation (24h expiry)

## Open Follow-ups
- [ ] Test refresh token with mobile team
- [ ] Draft API consumer migration guide

## Context for Next Session
Auth refactor done but mobile compatibility untested.

Modes

Mode	Command	What's Captured
Full	`"Capture this session"`	Decisions + questions + follow-ups + context
Quick	`"Quick capture"`	Decisions + follow-ups only
Tagged	`"Capture for project:API"`	Full capture tagged to a project

Tips

Run at the end of every substantive session — makes next-session startup instant
60-day auto-pruning — old entries are automatically cleaned up
Reverse chronological — newest entries at top of the session log
Works with any project — tag entries with project:name for filtering

Troubleshooting

"Nothing to capture" Session was too brief — only substantive work sessions get logged

Session log file doesn't exist It's created automatically on first run

Handoff not loading in next session Check that your handoff file path matches: ~/.claude/handoff.md

Session Capture & Handoff