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.
- Installs
- 215
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/gastownhall/beads --skill handoff- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads handoff automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
- If you provide a message, it's sent as handoff mail to yourself
gt handoffrespawns your session with a fresh Claude- New session auto-primes via SessionStart hook
- 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:
-
If user provided a message, send handoff mail:
gt mail send <your-address> -s "HANDOFF: Session cycling" -m "<message>" -
Run the handoff command:
gt handoff
The new session will find your handoff mail and hooked work automatically.
FAQ
What does the handoff skill do?
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.
How do I install handoff?
Run npx skills add https://github.com/gastownhall/beads --skill handoff in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/handoff/ (personal) or .claude/skills/handoff/ (project).
Which AI agents can use handoff?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is handoff safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains handoff?
It is published by gastownhall in gastownhall/beads. It has 215 recorded installs.
More from gastownhall/beads
beads
gastownhall/beads
Dolt-powered issue tracker for multi-session work with dependencies and persistent memory across conversation compaction. Use when work spans sessions, has blockers, or needs context recovery after compaction. Trigger with "create task", "what's ready", "track this work", "resume after compaction". Make sure to use this skill whenever managing multi-session work, tracking dependencies, or recovering context.
beads-docs
gastownhall/beads
Open the skill to read its SKILL.md instructions.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.