agents_switch — субагент для Claude Code: что делает и как установить
Субагент agents_switch для Claude Code переносит запущенных и остановленных агентов на другой лаунчер за один вызов. Срабатывает по запросу пользователя при контроле лимитов подписки.
MIT ★ 395 обновлён 2026-11-16
.claude/agents/agents_switch.mdЧто делает agents_switch
Субагент переключает сессии агентов Claude Code на целевой лаунчер прямо на машинах пользователя, сохраняя тот же контекст разговора и терминал. Инструмент фильтрует цели по списку agents, имени компьютера machine или исходному окружению from_launcher, где значением по умолчанию служит claude. Если агент остановлен из-за исчерпания лимита, он сразу продолжает работу на новом лаунчере, а занятые сессии ставятся в очередь до завершения текущего шага.
Процесс поддерживает параметр preview: сначала вызов собирает отчёт о планируемых изменениях, а реальное переключение запускается после подтверждения. Очередь на перенос сбрасывается через сутки или при ручной смене лаунчера. Если проверка отклоняет сессию из-за неподдерживаемой модели или другого CLI, агент остаётся без изменений с выводом причины отказа.
Какие задачи решает
- перенести группу агентов на запасной лаунчер при исчерпании квоты
- сменить модель или уровень reasoning effort сразу у нескольких сессий
- поставить переключение занятого агента в очередь без сброса контекста
- проверить статус и запланировать миграцию агентов через предварительный просмотр
Примеры запросов агенту
- Покажи в режиме preview, что произойдёт при переводе всех агентов с claude на другой лаунчер
- Переключи остановленные агенты с лимитом на резервный лаунчер
- Перенеси сессию с id 8a12bc4f на локальный лаунчер с моделью claude-3-5-sonnet
Как установить agents_switch
Вручную: положить файлы
.claude/agents/agents_switch.mdДля всех проектов — ~/.claude/agents/. Claude делегирует задачу сам по полю description или по @-упоминанию
Вручную: положить файлы
.codex/agents/agents_switch.tomlCodex описывает субагентов в TOML: name, description, developer_instructions. Текст из Markdown перенесите в developer_instructions вручную. Для всех проектов — ~/.codex/agents/
Вручную: положить файлы
.cursor/agents/agents_switch.mdCursor понимает и .claude/agents/
По шагам, с командами для каждой платформы: Субагенты Claude Code: как создать, вызвать и не утопить контекст
Вопросы об agents_switch
Как установить agents_switch в Claude Code?
Добавьте файл субагента по пути .claude/agents/agents_switch.md в корень вашего проекта.
Что делает agents_switch?
Он массово переводит агентов Claude Code на указанный лаунчер, учитывая их текущий статус: активные ставятся в очередь, а остановленные лимитом продолжают диалог.
Что происходит, если целевой лаунчер не запущен на машине?
Проверка безопасности отклоняет такой перевод, оставляет агента на исходном лаунчере и возвращает строку с описанием ошибки.
Исходный текст
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