agents_switch — Claude Code subagent: what it does, how to install
agents_switch — a subagent for Claude Code moves multiple running or stopped agents to a different launcher in a single invocation. Executes when requested to manage subscription usage quotas.
MIT ★ 395 updated 2026-11-16
.claude/agents/agents_switch.mdWhat agents_switch does
The tool migrates Claude Code sessions to a target launcher on their host machines while retaining the exact same terminal and chat history. Targets can be selected explicitly via agents or filtered globally through machine and from_launcher, which defaults to claude. Agents halted by usage boundaries swap immediately to resume output, while active workers queue up until their ongoing turn finishes.
Running with preview: true dry-runs the operation across targeted sessions and outlines intended actions before applying updates. Queued switches automatically expire after twenty-four hours or if the session moves elsewhere in the interim. Any session that fails compatibility checks, such as an unresolvable default model or an alien CLI, remains on its launcher alongside a status note.
What it helps with
- batch migrate agent sessions across launchers during subscription limits
- apply specific model overrides and reasoning effort to active agents
- queue launcher transitions for busy tasks without interrupting output
- preview migration outcomes across machines before applying state changes
Example prompts for the agent
- Preview moving all default launcher agents to the alternative launcher
- Switch agent sessions halted by token limits to the fallback launcher
- Move session 8a12bc4f on machine alpha to the new launcher using a specific model
How to install agents_switch
Manually: put the files in place
.claude/agents/agents_switch.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/agents_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/agents_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 agents_switch
How to install agents_switch in Claude Code?
Place the subagent definition file into your project at .claude/agents/agents_switch.md.
What does agents_switch do?
It transfers Claude Code agent sessions to another launcher in bulk, preserving terminal sessions and scheduling active agents for transition after their turn.
How are incompatible agents handled during a batch switch?
Checks reject incompatible runtimes or missing models, leaving the target agent on its existing launcher and printing the exact failure reason.
Source text
agents_switch.md · MIT
Move many Claude Code agents to another launcher on their computers in one call. Use it when the user asks to move agents to another launcher ("move everything on the default launcher to X", "switch these to X"), for example because they watch their subscription quota; never on your own. Name the agents in `agents`, or leave it out to take every Claude Code agent (running ones, and stopped ones Persona started), narrowed by `machine` and `from_launcher` (`claude` is the default launcher). First call it with `preview` true and tell the user what it will do with each agent, then call it again without `preview` once they agree; when the user already named exactly which agents and where, one call is enough. Each agent goes as its state allows: one its usage limit stopped is switched now and goes on with what it was doing; an idle one is switched now and nothing is sent (it waits on the new launcher for the next message); one that is working, waits for the user (a question, a permission, a plan), is starting or has background work is queued and switched when its turn ends (with the usage-limit continuation if that turn ended on a limit); a stopped one Persona started has the launcher it resumes on changed, so its next Resume, or the message that resumes it, comes up on the new launcher; one the checks refuse (another CLI, a runtime's session, an assistant conversation, a launcher that does not run there, a model the launcher's default cannot be read for: give model) is reported and left as it is, and so is one whose switch failed on its computer (it is back on its launcher; not tried again: tell the user why). The answer has one line per agent: switched and continued, switched, switched (takes effect when resumed), queued, or refused with why. A queued switch is dropped if the agent moves to another launcher meanwhile or after a day; if it stops meanwhile, its Resume is pointed at the new launcher instead; agents_list shows queued ones as switch_queued=. The switch is the same as the user's from the agent's chat: same conversation, same terminal.
```json
{
"type": "object",
"required": ["launcher"],
"properties": {
"launcher": {
"type": "string",
"description": "the launcher to move them to, by its name on their computers"
},
"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 each has it"
},
"agents": {
"type": "array",
"description": "the agents to move; empty: every Claude Code agent (running, or stopped and started by Persona) that machine and from_launcher keep",
"items": {
"type": "object",
"required": ["session_id"],
"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"
}
}
}
},
"machine": {
"type": "string",
"description": "without agents: only this computer's agents"
},
"from_launcher": {
"type": "string",
"description": "without agents: only the agents running on this launcher (claude: the default)"
},
"preview": {
"type": "boolean",
"description": "true: only say what it would do with each agent; nothing is switched or queued"
}
}
}
```
© nwverse · MIT · nwverse/persona