🇺🇸English

Handoff - Session Cycling for Gas Town Agents

Hand off your current session to a fresh Claude instance while preserving work context.

When to Use

• Context getting full (approaching token limit)
• Finished a logical chunk of work
• Need a fresh perspective on a problem
• Human requests session cycling

Usage

/handoff [optional message]

How It Works

1. If you provide a message, it's sent as handoff mail to yourself
2. gt handoff respawns your session with a fresh Claude
3. New session auto-primes via SessionStart hook
4. Work continues from your hook (pinned molecule persists)

Examples

# Simple handoff (molecule persists, fresh context)
/handoff

# Handoff with context notes
/handoff "Found the bug in token refresh - check line 145 in auth.go first"

What Persists

• Hooked molecule : Your work assignment stays on your hook
• Beads state : All issues, dependencies, progress
• Git state : Commits, branches, staged changes

What Resets

• Conversation context : Fresh Claude instance
• TodoWrite items : Ephemeral, session-scoped
• In-memory state : Any uncommitted analysis

Implementation

When invoked, execute:

1. If user provided a message, send handoff mail:

   gt mail send <your-address> -s "HANDOFF: Session cycling" -m "<message>"
   

2. Run the handoff command:

   gt handoff
   

The new session will find your handoff mail and hooked work automatically.

Weekly Installs

122

Repository

steveyegge/beads

GitHub Stars

19.7K

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubFailSocketPassSnykPass

Installed on

opencode116

claude-code114

codex113

gemini-cli113

github-copilot110

cursor108