Skip to main content
subagent CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/agent_switch.md
Open on GitHub

What 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 abc12345 on this computer to another launcher and continue its work.
  • Switch the current agent to the Launcher name launcher and ask it to continue reviewing the tests.

How to install agent_switch

Manually: put the files in place

.claude/agents/agent_switch.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

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

Similar subagents

Subagents catalog →

From the same set61

The whole set →
task_decided The task_decided Claude Code subagent records an owner's answer to a pending task decision. It captures the choice when the owner gives it in the conversation. CX Codex ★ 395repo stars agents_list agents_list — a subagent for Claude Code and Codex monitoring running herdr sessions across user machines. Displays active jobs, pending approvals, and subscription limits. CX Codex ★ 395repo stars task_scope task_scope — a subagent for Claude Code revises a supervised task after it starts. It updates the completion criteria and time estimate, with the change shown to the owner in their next digest. CX Codex ★ 395repo stars agent_archive Subagent for Claude Code moves a coding agent session from the active list to the archive. It triggers when cleaning up or archiving agent sessions. CX Codex ★ 395repo stars worker_supervise worker_supervise — a subagent for Claude Code supervises background workers launched with task_plan. It checks submitted evidence against completion criteria and updates worker status via task_review. CX Codex ★ 395repo stars agents_switch 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. CX Codex ★ 395repo stars standing_actions Claude Code subagent standing_actions classifies the operations authorized by an agent confirmation card. CX Codex ★ 395repo stars agent_send This Claude Code subagent sends messages to another agent and can assign it supervised work. It can resume a stopped agent with its context when the recorded stop reason allows it. CX Codex ★ 395repo stars

Project sponsors

Companies that keep this analytics open