Claude Handoff – Hand Off the Current Session to a Background Agent

Skill Overview

Claude Handoff is a Claude Code slash command that organizes the current conversation into a handoff summary and immediately uses it to launch a background agent, allowing the new session to continue the work instead of requiring you to explain the context again.

Use Cases

1. The context is nearly full, but the task is unfinished: When the current session is approaching its context limit, rather than struggling to continue, hand off the goals, progress, and to-do items to a brand-new background agent, which can continue with a clean context.
2. You want to make progress on multiple tasks in parallel: The foreground session can continue discussing solutions or troubleshooting issues while handing clearly defined refactoring, migration, or batch-editing tasks to a background agent. The two processes do not block each other.
3. You want to continue across time or devices: Hand off unfinished work before leaving for the day, then open the session list on another machine the next day to review the results without having to restate the requirements.

Core Features

1. Generate a structured handoff summary: Organize the information that genuinely needs to be passed on from the current conversation—the task objective, completed work, outstanding work, key file paths, and approaches that have been ruled out. The summary is not a simple repetition of the chat history; it is an action guide for the next agent.
2. Launch a background agent with one command: Execute claude --bg --name "<task name>" "<handoff summary>" directly. The background agent starts in the current working directory and returns immediately without occupying the current terminal. The command requires a descriptive name supplied via -n/--name. This name appears in the task list, session selector, and terminal title, making it easy to manage later with claude agents.
3. Keep the handoff focused and secure: The summary includes a “Suggested Skills” section identifying which Skills the next agent should invoke. It also instructs the agent not to duplicate the contents of existing artifacts (specifications, plans, ADRs, issues, commits, or diffs), but to reference them by path or link only, and to redact sensitive data such as API keys, passwords, and personal information—because the summary itself becomes that agent’s prompt.

Frequently Asked Questions

Does Claude Handoff save the handoff summary to a file?

No. The summary is not written to disk; it is passed directly to the background agent as a prompt. Therefore, if you want to review what was communicated later, you need to inspect the session itself in the task list.

Where does the background agent run, and how can I check its progress?

It starts in your current working directory and returns immediately without blocking the current terminal. You can later use claude agents to view and manage all background tasks, including renaming, switching, and terminating them.

Can I include an API key or password in the handoff summary?

No. The summary becomes the new agent’s prompt, so any keys, passwords, or personal information included in it will enter that session. Always redact such information before handing off, replacing it with placeholders or references to local secret-management methods.

Usage Boundaries

• This is a manually triggered command (disable-model-invocation: true); Claude will not invoke it automatically. You must explicitly enter /claude-handoff.
• It requires the claude CLI to be installed and logged in locally; --bg and claude agents are capabilities provided by the CLI.
• The command accepts arguments to describe the next session’s focus, and the summary adjusts its emphasis accordingly. If no arguments are provided, it is written based on the overall objective of the current conversation.