handoff

Hand Off to Remote Claude Code

Transfer the current work to a Claude Code instance running on a sprite in the cloud. This enables background processing, parallel work, or offloading long-running tasks.

Workflow

1. Ensure sprite is ready

   • Check for active sprite with sprite use
   • If none, create one or ask user to run /sprite:create

2. Generate handoff context

   • Create a summary of the current conversation/task
   • Combine with user's task description
   • Format as a prompt for the remote Claude

3. Run the handoff using the CLI tool

   $CLAUDE_PLUGIN_ROOT/bin/sprite-handoff run <sprite-name> "<prompt>" [flags]
   

   The run command handles everything:

   • Creates git worktree for session isolation
   • Syncs all git-tracked files
   • Creates initial commit
   • Retrieves Claude OAuth token
   • Launches Claude Code on the sprite

   Available flags:

   • --model <model> - Specify model (sonnet, opus, haiku)
   • --max-budget <amount> - Set spending limit in USD
   • --source <dir> - Source directory (default: current dir)
   • -v - Verbose output

4. Return session info

   • The command outputs the session ID
   • Explain how to resume: sprite-handoff run <sprite> "<prompt>" --resume <session-id>
   • Explain how to pull changes: sprite-handoff pull <session-id>

Handoff Prompt Format

The prompt passed to the run command should include context:

## Context
[Summary of conversation and what was being worked on]

## Project State
[Key files, recent changes, current status]

## Task
[User's task description - what to continue working on]

## IMPORTANT: Commit Your Changes
You MUST commit all changes before finishing. The user will pull your work
using `git diff`, so uncommitted changes will be lost.

When done, run:
  git add -A && git commit -m "Description of changes"

## Instructions
- Work autonomously on this task
- Commit all changes with a descriptive message when complete
- Write a summary of what was done to HANDOFF_RESULT.md