
handoff
Hand off context to any AI coding agent
- version
- 1.0.0
- GitHub stars
- 146
Install
/plugin install handoff@handoff-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add willseltzer/claude-handoff.
Contents
Discovered from sourceSkills 1
Handoff Detection
On Session Start
Check if HANDOFF.md exists in the working directory. If found:
- Read it silently
- Tell the user: "Found a handoff from a previous session: [title]. [1-sentence goal]. Resume from here?"
- If they agree, follow
/handoff:resumeflow
Trigger Words
Activate when user says: "handoff", "hand off", "pass this to", "continue later", "pick up where", "transfer context", "save state", "resume", "take over"
Creating vs Resuming
- User wants to create: They're wrapping up or switching agents → use
/handoff:create - User wants to resume: They're starting fresh with existing handoff → use
/handoff:resume
Proactive Suggestions
Consider suggesting a handoff when:
- User says "I need to go" or "let's stop here"
- A significant milestone is reached
- You've been working for a long time with lots of context
Say: "Want me to create a handoff so you (or another agent) can continue later?"
Commands
| Command | Use When |
|---|---|
/handoff:create | Full handoff with all context |
/handoff:quick | Minimal handoff, just essentials |
/handoff:resume | Continue from existing handoff |
Commands 3
Create a HANDOFF.md file that enables ANY AI coding agent to continue this work seamlessly.
Gather Context First
Run these commands to understand current state:
git status- see uncommitted changesgit diff --stat- see what files changedgit log --oneline -5- recent commits from this session
Review the conversation history to extract:
- The original task/goal
- What was completed
- What was tried and didn't work (critical - saves hours)
- Key decisions and their rationale
- User preferences expressed during the session
- Error messages encountered and how they were resolved
Write HANDOFF.md
Use this structure (omit empty sections, but NEVER omit Failed Approaches if any exist):
# Handoff: [Brief Task Title]
**Generated**: [date/time]
**Branch**: [git branch]
**Status**: [In Progress / Blocked / Ready for Review]
## Goal
[1-2 sentences: what the user wants to achieve]
## Completed
- [x] [Specific completed item]
- [x] [Another completed item]
## Not Yet Done
- [ ] [Remaining task - be specific]
- [ ] [Another remaining task]
## Failed Approaches (Don't Repeat These)
[IMPORTANT: Always include this if anything was tried and abandoned. Be specific:]
- What was attempted
- Why it failed (error message, performance issue, design flaw)
- Why the current approach is better
Example:
> Tried using passport.js for OAuth but it conflicted with existing Express middleware (req.user was undefined). Switched to oauth4webapi which works directly with fetch.
## Key Decisions
| Decision | Rationale |
|----------|-----------|
| [Choice made] | [Why this approach] |
## Current State
**Working**: [What's functional right now]
**Broken**: [What's not working, error messages if relevant]
**Uncommitted Changes**: [Summary of unstaged/staged changes]
## Files to Know
| File | Why It Matters |
|------|----------------|
| `path/to/key/file.ts` | [Brief description] |
## Code Context
[Include actual code the next agent needs. Don't describe - show:]
**Key interfaces/signatures** (so the agent knows how to call/modify them):
```typescript
// Example: hook signature
function useAuth(): { user: User | null; login: (creds: Credentials) => Promise<void> }
API request/response shapes (if backend work):
// POST /api/resource - example response
{ "id": 123, "status": "created" }
Non-obvious logic (anything tricky that isn't self-documenting)
Resume Instructions
[Be extremely specific. Not "test the feature" but step-by-step with expected outcomes:]
- [Setup step if needed - migrations, env vars, etc.]
- [First action with exact command or file to edit]
- [Verification step with expected outcome]
- Expected: [what should happen]
- If it fails: [what to check]
Example:
- Run
alembic upgrade headto apply migrations - Start server:
./start.sh - Test login flow: POST to /api/login with test@example.com / testpass
- Expected: 200 response with { token: "..." }
- If 401: Check user exists in DB
Setup Required
[Only if there are prerequisites the next agent needs:]
- Environment variables:
API_KEY,DATABASE_URL - Test accounts: test@example.com / password123
- Required services: Redis must be running on :6379
Edge Cases & Error Handling
[Document known edge cases and how they're handled - or should be:]
- What happens if [X fails]? → [current behavior or "not handled yet"]
- What if user does [Y]? → [expected behavior]
Warnings
[Gotchas, things that look wrong but are intentional, or traps to avoid]
## Guidelines
- **Failed approaches are mandatory** - if anything was tried and abandoned, document it
- **Show code, don't describe** - include actual signatures, interfaces, response shapes
- **Testing steps need expected outcomes** - "verify it works" is useless
- Be brutally concise - every word should earn its place
- Include error messages verbatim when relevant
- Use file paths relative to repo root
- If there's a blocker, say so prominently
- Omit empty sections (except Failed Approaches - say "None" if truly nothing failed)
Save to `HANDOFF.md` in the working directory. If `$ARGUMENTS` specifies a path, use that instead.
Create a minimal HANDOFF.md with only the essentials. Use this for simple tasks or quick context transfers.
Output this exact format (fill in the brackets):
# Handoff: [task in 5 words or less]
**Goal**: [one sentence]
**Done**: [comma-separated list of completed items, or "Nothing yet"]
**Next**: [the single most important next step]
**Watch out**: [one key warning, or "Nothing special"]
That's it. No extras. Save to HANDOFF.md or the path in $ARGUMENTS.
Resume work from a handoff created by another AI agent.
1. Find and Read the Handoff
Look for the handoff document:
- If
$ARGUMENTSis provided, read that path - Otherwise, check for
HANDOFF.mdin the current directory - If not found, ask the user for the path
Read the entire handoff document carefully.
2. Verify State Hasn't Drifted
Run git status and git log --oneline -3 to check:
- Is the branch the same as documented?
- Have there been commits since the handoff was created?
- Are there uncommitted changes not mentioned in the handoff?
If state has drifted significantly, warn the user:
"The repo has changed since this handoff was created. [describe changes]. Should I proceed with the handoff context anyway, or would you like to describe what changed?"
3. Summarize to the User
Give a brief summary (not the whole document):
Resuming from handoff: [title]
Goal: [1 sentence]
Status: [X of Y tasks complete]
Next: [First item from Resume Instructions]
Ready to continue?
4. Heed the Warnings
Pay special attention to:
- Failed Approaches - Don't repeat these mistakes
- Warnings - Respect gotchas from the previous agent
- Key Decisions - Follow established patterns unless user asks to change
5. Continue the Work
Start with the first item in "Resume Instructions" unless the user redirects.
If the handoff is unclear on something critical, ask the user rather than guessing.
Sponsors
Details
- Marketplace
- willseltzer/claude-handoff
- Source
- willseltzer/claude-handoff
- Category
- Community