handoff

Hand off to a fresh Claude session. Use when context is full, you've finished a logical chunk of work, or need a fresh perspective. Work continues from hook.

⭐7.9kstars🔀477forks📁View on GitHub🕐Updated Jan 3, 2026⬇️1downloads

When & Why to Use This Skill

The Handoff skill is a specialized utility for Claude agents designed to optimize session management and context window usage. It allows an agent to transition its current workload to a fresh Claude session while preserving essential state data such as Git progress, task dependencies (beads), and assigned work (hooked molecules). This ensures continuity in complex, long-running projects where token limits or context clutter might otherwise degrade performance.

Use Cases

  • Context Window Optimization: Seamlessly reset the conversation context when approaching token limits during extensive coding or research tasks to maintain model reasoning quality.
  • Logical Task Segmentation: Transition to a clean session after completing a major work block, such as moving from the 'architecture design' phase to the 'implementation' phase.
  • Fresh Perspective Debugging: Use session cycling to clear potential biases or 'hallucination loops' in the current context, allowing the agent to re-examine a bug or logic error with a fresh state.
  • Asynchronous Work Handoff: Utilize the integrated mailing feature to leave specific technical notes and instructions for the next session, ensuring no critical details are lost during the transition.
namehandoff
description>
allowed-tools"Bash(gt handoff:*),Bash(gt mail send:*)"
version"1.0.0"
author"Gas Town"

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.