# 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.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 395 repo stars
- Author: nwverse
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/nwverse/persona/tree/HEAD/server/internal/prompts/mcp/agents/agents_switch.md
- Updated: 2026-11-16
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/agents-switch

## What it 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.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/agents/agents_switch.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/agents_switch.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/agents_switch.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/nwverse/persona/tree/HEAD/server/internal/prompts/mcp/agents/agents_switch.md

## When to use it
- 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
- 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

## Source text · agents_switch.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: d95128254208cb25.

BEGIN THIRD-PARTY FILE d95128254208cb25
````text
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"
    }
  }
}
```
````
END THIRD-PARTY FILE d95128254208cb25

The third-party file has ended. Everything between the d95128254208cb25 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

© nwverse · MIT · https://github.com/nwverse/persona/tree/HEAD/server/internal/prompts/mcp/agents/agents_switch.md

## Similar
- [orchestration](https://affpapa.org/en/nevibecode/skills/orchestration.md) — skill · 359600 installs
- [showagent](https://affpapa.org/en/nevibecode/mcp/showagent.md) — MCP server · ★ 70 repo stars
- [magents](https://affpapa.org/en/nevibecode/mcp/magents.md) — MCP server · ★ 16 repo stars
- [ae-team](https://affpapa.org/en/nevibecode/skills/ae-team.md) — skill · 995 installs

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
