agent_switch — Claude Code subagent: what it does, how to install
This subagent for Claude Code moves a running agent to another launcher on the same computer. It switches sessions only when the user asks.
MIT ★ 395 updated 2026-11-16
.claude/agents/agent_switch.mdWhat agent_switch does
agent_switch quits the current Claude Code process and resumes it in another launcher, keeping the terminal and conversation. A new task can be sent in the switch request. If a usage limit stopped the agent, it can resume its previous work without new text.
The switch runs only on an explicit user request. It refuses while the agent is working or starting, waiting for a question or permission, running background work, or holding a draft in its input box; nothing is sent or left queued. The target launcher must run on that computer and be signed in. This does not move stopped or read-only agents, assistant conversations, Codex sessions, or other agents.
What it helps with
- move a running Claude Code session to another launcher
- resume work after an agent hits its usage limit
- send a new task to an agent in a different launcher
Example prompts for the agent
- Move agent
abc12345on this computer to another launcher and continue its work. - Switch the current agent to the
Launcher namelauncher and ask it to continue reviewing the tests.
How to install agent_switch
Manually: put the files in place
.claude/agents/agent_switch.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/agent_switch.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/agent_switch.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about agent_switch
How do I install agent_switch in Claude Code?
Add the subagent file at .claude/agents/agent_switch.md.
What does agent_switch do?
It resumes a running Claude Code agent in another launcher on the same computer, keeping its terminal and conversation.
When will agent_switch refuse a transfer?
It refuses while an agent is busy, starting, waiting for input, running background work, or has a draft in its input box. It also does not handle stopped agents, Codex sessions, or other agents.
Source text
agent_switch.md · MIT
Move a running Claude Code agent (from agents_list) to another launcher on its computer and go on with it, in one step: the agent is quit and resumed on that launcher in the same terminal, with the same conversation, and `text` is sent to it there. It is the switch the user makes from the agent's chat. Use it only when the user asked for it, for example when a subscription's usage limit stopped agents and the user wants them to go on with another provider now rather than wait for the reset; never on your own. The launcher must be one of that computer's (machines_list and agents_list show the names). The switch happens now or not at all: an agent that is working, waits for the user (a question, a permission, a plan), is starting, has background work its quit would end, or has a draft or a dialog in its input box is refused with nothing typed and nothing left waiting; tell the user why, and try again once it has stopped if they still want it. Other refusals say why too (a launcher that does not run there or is not signed in, a model the launcher's default cannot be read for: give model). Not for stopped agents (agent_send with resume), assistant conversations, read-only agents, or Codex and other agents. An agent its usage limit stopped goes on with what it was doing when `text` is left out; any other agent needs `text`. Its usage-limit continuation, if one was due, is not sent afterwards.
```json
{
"type": "object",
"required": ["machine", "session_id", "launcher"],
"properties": {
"machine": {
"type": "string",
"description": "the machine's id or name, as agents_list shows it"
},
"session_id": {
"type": "string",
"description": "the agent's session id, or its first 8 characters"
},
"launcher": {
"type": "string",
"description": "the launcher to move it to, by its name on that computer"
},
"model": {
"type": "string",
"description": "a model of that launcher; empty: the launcher's default"
},
"effort": {
"type": "string",
"description": "the reasoning effort on the new launcher; empty: as it is"
},
"text": {
"type": "string",
"description": "what the agent does on the new launcher, sent as the user would type it; empty only for an agent its usage limit stopped (it goes on with what it was doing)"
}
}
}
```
© nwverse · MIT · nwverse/persona