megalithic/handoff

Handoff / Pickup

Save and restore session context across pi sessions. Use when context window is full and model quality is degrading.

Script location: ~/.dotfiles/home/common/programs/ai/pi-coding-agent/skills/handoff/scripts/

Commands

/handoff - Save current session state

When the user says /handoff:

1. Write a temp file with the handoff content
2. Run the script with --file

# Write content to temp file, then save handoff
cat > /tmp/handoff-content.md << 'HANDOFF'
## What I was working on

{Clear description of the task/goal}

## Current state

{Where things stand - what's done, what's in progress}

## Key files

- `path/to/file.ts` - Description of changes
- `path/to/other.ts` - What was done here

## Decisions made

- Decision 1 and why
- Decision 2 and reasoning

## Next steps

1. [ ] First thing to do next
2. [ ] Second thing
3. [ ] Third thing

## Blockers / Concerns

- Any issues or things to watch out for

## Context for pickup

{Any additional context that would help understand the situation}
HANDOFF

~/.dotfiles/home/common/programs/ai/pi-coding-agent/skills/handoff/scripts/handoff.sh --file /tmp/handoff-content.md --title "Brief title"
rm /tmp/handoff-content.md

The script auto-captures:

• Current bookmark (for pickup verification)
• jj status (working copy state)
• Recent commits
• Uncommitted changes (diff stat)

/pickup - Resume from last handoff

When the user says /pickup:

# Get the latest handoff for current session
~/.dotfiles/home/common/programs/ai/pi-coding-agent/skills/handoff/scripts/pickup.sh

# Or specify a session
~/.dotfiles/home/common/programs/ai/pi-coding-agent/skills/handoff/scripts/pickup.sh mega
~/.dotfiles/home/common/programs/ai/pi-coding-agent/skills/handoff/scripts/pickup.sh rx

After retrieving the handoff:

1. Check bookmark verification section (at end of output)

   • If "Bookmarks match" → Proceed, but still confirm with user
   • If "Bookmark mismatch" → Present options to user, wait for response
   • If "No bookmark was set" → Ask user what bookmark to use

2. Handle bookmark mismatch before doing anything else:

   ⚠️ Bookmark mismatch detected:
   - Handoff was on: `feature-branch`
   - Currently on: `main`
   
   Options:
   1. Switch to `feature-branch` to continue where we left off
   2. Stay on `main` and start fresh
   3. Create a new bookmark for this work
   
   Which would you like?
   

3. Once bookmark is confirmed:

   • Read and understand the document
   • Verify current state matches (check jj status, key files exist)
   • Summarize back to user: "Picking up where we left off: {brief summary}"
   • Confirm before continuing: "Ready to continue with {next step}?"
   • Start from the "Next steps" section

IMPORTANT: Never proceed with work until bookmark situation is resolved. The user must explicitly confirm which bookmark to use.

List available handoffs:

~/.dotfiles/home/common/programs/ai/pi-coding-agent/skills/handoff/scripts/pickup.sh --list
~/.dotfiles/home/common/programs/ai/pi-coding-agent/skills/handoff/scripts/pickup.sh --list mega

Storage Location

~/.local/share/pi/handoffs/
├── mega/
│   ├── 2026-02-19T14-30-00.md
│   └── 2026-02-19T16-45-00.md
├── rx/
│   └── 2026-02-18T09-00-00.md
└── canonize/
    └── 2026-02-17T11-20-00.md

Handoff Document Format

# Handoff: {brief title}

**Session:** mega
**Time:** 2026-02-19 14:30:00 EST
**Working Directory:** /Users/seth/projects/myapp
**Bookmark:** feature-auth-refactor

## What I was working on

{Clear description of the task/goal}

## Current state

{Where things stand - what's done, what's in progress}

## Key files

- `src/auth/login.ts` - Modified authentication flow
- `tests/auth.test.ts` - Added new test cases
- `docs/api.md` - Updated API documentation

## Recent changes

{Summary of uncommitted changes or recent commits}

## Decisions made

- Decided to use JWT instead of sessions because...
- Chose to split the module into two files for...

## Next steps

1. [ ] Finish implementing the refresh token logic
2. [ ] Add error handling for expired tokens
3. [ ] Update the client SDK

## Blockers / Concerns

- Need to verify the token expiry edge case
- Performance concern with the database query in `getUser()`

## Context for pickup

{Any additional context that would help the next session understand the situation}

Best Practices

When to handoff

• Context window feeling "full" (model starts hallucinating or forgetting)
• Before taking a break from a complex task
• Before switching to a different project
• When you want a "checkpoint" of the current state

Writing a good handoff

• Be specific - Include file paths, not just descriptions
• Document decisions - Note non-obvious choices and reasoning
• Concrete next steps - List actionable items, not vague goals
• Note surprises - Mention anything tricky or unexpected
• Include blockers - What might stop progress?

Picking up

1. Run /pickup to retrieve the handoff
2. Verify state: jj status, check key files exist
3. Summarize back to user before continuing
4. Ask for confirmation before starting work
5. Begin with "Next steps" section