@taskless-app/swarm

Рой AI-агентов, которые пишут код за вас — под управлением Taskless.

Что это

CLI, который поднимает у вас на машине рой дронов — автономных AI-агентов на базе Claude Code. Каждый дрон берёт задачу, пишет код в изолированной ветке и открывает pull request. Задачи, координация и прогресс — в вашем воркспейсе Taskless.

Для чего

Превратить задачи в готовый код без ручной работы. Ставите задачи в Taskless — рой сам разбирает крупную работу на дронов, они делают её параллельно и присылают PR на ревью. Вы дирижируете, а не печатаете.

Как пользоваться

Нужно: Node ≥ 22, установленный Claude Code, аккаунт Taskless. Дроны роя пишут код через claude CLI в изолированных git worktree — репозиторий, с которым работаете, тоже должен быть на месте (склонирован локально).

Три команды, одинаковые на macOS, Linux и WSL:

npm i -g @taskless-app/swarm
swarm install                      # довести окружение машины до рабочего состояния
swarm login --workspace <slug>     # войти в свой Taskless-воркспейс
swarm start                        # поднять рой: уходит в фон, терминал остаётся вам
swarm --help                       # список остальных команд (spawn/ls/questions/answer/…)

Без установки — одной командой на задачу (тогда swarm install пропускается, и за окружение отвечаете вы):

npx @taskless-app/swarm login --workspace <slug>
npx @taskless-app/swarm start

Установка окружения: swarm install и swarm doctor

swarm install — не список советов, а установка: команда проверяет пункты и делает сама всё, что может, а там, где без вас нельзя, показывает точную строку и объясняет зачем. Проверяются: версия Node, claude и gh (включая вход в GitHub), глобальный пакет роя и его версия против опубликованной, playwright-core и системные библиотеки Chromium для скриншотов, Docker (только если он нужен найденному репозиторию), клоны репозиториев и SWARM_REPO, живой токен и уже поднятый демон.

swarm install          # проверить и довести до рабочего состояния
swarm install --yes    # заранее разрешить sudo-команды (неинтерактивный запуск)
swarm doctor           # ТА ЖЕ проверка без установки: что не так и как чинить

Что стоит знать про поведение:

• Разница платформ спрятана внутрь. На macOS — Homebrew и обычно без повышения прав; на Linux и в WSL — системный пакетный менеджер (apt/dnf/pacman/zypper/apk), а значит sudo. Команда для вас одна и та же.
• Про права — честно. Там, где нужен sudo, команда показывает точную строку и что именно она поставит, и спрашивает согласие. Не интерактивный запуск без --yes — строка просто печатается, пункт остаётся красным. Молча повышать права на вашей машине она не будет.
• Ставится только то, чего действительно нет. Каждый пункт сперва проверяется: на маке, где Chromium и так поднимается, системные библиотеки никто ставить не полезет.
• Повторный запуск безопасен. На машине, где всё стоит, swarm install ничего не делает и не перезапускает — просто говорит «готово». Живой токен не требует повторного swarm login; работающий демон не глушится и второй копией на тот же порт не подменяется — команда скажет, что его нужно перезапустить самому.
• Не притворяется, что всё хорошо. Если Chromium не поднимается — так и написано: скриншоты недоступны, UI-задачи будут сдаваться без них. Проверка настоящая: рой реально запускает headless Chromium тем же кодом, что swarm shot, — потому что наличие файлов ничего не доказывает (в WSL пакет на месте, а libnss3.so нет).

swarm doctor печатает состояние и причину — его вывод и стоит присылать, когда что-то не работает, вместо переписки «попробуй запустить, скажи что вывелось».

Обновление: swarm update

swarm update           # обновить рой до опубликованной версии

Обновление своей же программы — её собственная работа: помнить, каким менеджером поставлен пакет (npm/pnpm/bun/yarn — глобальные каталоги у них разные) и что пакет называется не так, как команда, вы не обязаны. Версия уже свежая — команда так и скажет и ничего не сделает.

Демон сам говорит, что устарел: при старте, если установленная версия отстала от опубликованной, в лог уходит одна строка с точной командой обновления. И отдельно помните: Node держит модуль-граф с момента старта процесса, поэтому обновление пакета не переезжает в живой демон само — после swarm update нужен swarm stop && swarm start. Команда об этом напомнит, если демон поднят.

Пути к репозиториям указывать не нужно. Демон спрашивает у Taskless, за какие репозитории отвечает ваш рой (проекты с включённым роем), и сам находит их клоны на машине: у каждого клона в .git/config записан origin, и по нему он сопоставляется с репозиторием проекта. Смотрит в привычных местах (~/projects, ~/code, ~/src, ~/work, …) на три уровня вглубь — на типовой машине это десятки миллисекунд. Клоны лежат где-то ещё — скажите один раз, swarm start --repo <путь>, дальше запомнится.

Что нашлось и где — печатает swarm status. Оттуда же видно два случая, о которых рой не молчит: клона нет (тогда прогоны этого репозитория будут стоять — рой сам не клонирует, диск ваш) и клонов два (рой называет обе копии и говорит, в какой работает). То же самое видно в Taskless: на вкладке «Рой» проекта — отдельным пунктом онбординга, а прогон, чей репозиторий не держит ни одна машина, прямо говорит, чего он ждёт, вместо того чтобы молча стоять в очереди.

Свои каталоги поиска — SWARM_SCAN_ROOTS=~/dev,/srv/repos (порядок значим: при двух копиях побеждает первый корень); выключить поиск целиком — SWARM_SCAN_ROOTS=off. Глубина — SWARM_SCAN_DEPTH (по умолчанию 3), период пересборки карты — SWARM_REPO_MAP_MS (по умолчанию 15 минут; новый swarm-проект подхватится без перезапуска демона).

Демон открепляется от терминала. swarm start не занимает окно: процесс уходит в фон, а весь вывод пишется в ~/.taskless-swarm/overmind.log — тот самый файл, из которого агент читает хвост лога удалённо. Посмотреть: swarm logs -f. Нужен вывод прямо в терминале (отладка, systemd, docker, где фоном занимается супервизор) — swarm start --foreground (он же -f, --attach).

Команда не отчитывается о запуске раньше времени: она ждёт, пока демон реально поднимется, и только тогда говорит «поднят». Не поднялся — покажет хвост лога с настоящей причиной (занятый порт, отсутствующий токен) и завершится с ошибкой.

Полный гайд по настройке и запуску роя — на taskless.ru.

Остановить, приостановить, отключить машину

Гасить демона по имени процесса (pkill -f overmind) не нужно — есть штатные команды:

swarm status               # жив ли демон, на паузе ли рой, сколько дронов в работе,
                           # какие репозитории у роя и где нашлись их клоны
swarm doctor               # окружение машины: что не так и как чинить
swarm pause «причина»      # не брать НОВУЮ работу; живые дроны доработают
swarm resume               # снова брать работу
swarm stop                 # погасить демона на этой машине
swarm remove --yes         # отключить машину от роя целиком

swarm stop по умолчанию не обрывает дронов. Есть живые сессии — команда покажет, кто работает, и не станет их убивать: незапушенная работа дрона умирает вместе с ним. Дальше выбираете сами: swarm stop --wait (дождаться, новую работу рой в это время не берёт) или swarm stop --force (погасить сейчас, оборвав их).

Пауза переживает перезапуск. Она лежит файлом ~/.taskless-swarm/pause.json, поэтому перезагрузка машины не возвращает рой к работе молча. Поставить её можно и при лежащем демоне — тогда следующий swarm start поднимется уже на паузе. Пауза, поставленная из интерфейса Taskless, снимается командой на машине и наоборот: состояние одно, и оно же видно в парке машин («на паузе» — не то же самое, что «молчит» или «нет работы»).

swarm remove ≠ swarm logout. logout забывает токены на этой машине (перелогиниться); remove выводит машину из роя: гасит демона, убирает её из парка машин (её незавершённые прогоны освобождаются и уедут на другие машины) и стирает токены. Вернуть — swarm login && swarm start.

Перелогин — одна команда

Токен машины отзывается сам собой: вошли на второй машине, нажали «сбросить токен роя», выключили рой тумблером. Демон при этом жив и тикает, но работу не берёт, а в логе повторяет одну строку — «токен роя отозван … Почини одной командой: swarm login».

swarm login                # и всё: без stop, без start, без чтения логов

Команда сама разруливает демона: увидела поднятого — гасит его аккуратно (как swarm stop --wait: живые дроны доигрывают, новую работу рой в это время не берёт), поднимает страницу входа и поднимает демона обратно — уже с новым токеном. Перезапуск обязателен: токен читается один раз при старте процесса, иначе демон продолжил бы стучаться старым.

Ждать нечего — swarm stop --force в другом терминале оборвёт дронов и вход пойдёт сразу. Демон был погашен до команды — обратно она его не поднимает: было выключено, выключенным и останется. Вход не удался или вкладку закрыли — демон возвращается в то состояние, в котором был.

Кем исполнять дрона

Рою всё равно, какой агент внутри: всё, что знает про конкретный харнесс (как запустить, как передать задачу, как забрать результат, как понять, что прогон умер), спрятано за адаптером в src/executors/. Наружу торчит одинаковый прогон.

SWARM_EXECUTOR=claude-code swarm start   # по умолчанию: Claude Code (`claude`)
SWARM_EXECUTOR=codex       swarm start   # Codex CLI (`codex exec`)

Смена исполнителя — это настройка, а не правка демона: очередь, worktree, ревью, учёт стоимости, watchdog и воскрешение после обрыва работают одинаково. Что различается — прячет адаптер:

| | claude-code | codex | |---|---|---| | запуск | claude -p <промпт> | codex exec <промпт> | | продолжить оборванное | --continue | exec resume --last | | MCP-сервер роя | файл .swarm-mcp.json + --mcp-config | -c mcp_servers.overmind={…} | | результат прогона | один JSON в конце stdout | поток событий JSONL | | сессии (живость дрона) | ~/.claude/projects/<worktree> | ~/.taskless-swarm/executor-state/codex/<worktree> | | скиллы роли | --plugin-dir | текстом в промпте (флага нет) |

Путь к исполняемому файлу, если он не в PATH: SWARM_CLAUDE_BIN / SWARM_CODEX_BIN. Неизвестное значение SWARM_EXECUTOR — ошибка на старте, а не тихий откат на дефолт: «думал, поехали на другом» узнаётся иначе только из счёта.

Оговорки по codex: прайсинг его моделей пока пуст, поэтому стоимость таких прогонов считается нулём (лучше честный ноль, чем выдуманный тариф), а deny-правил на файловые тулы у него нет — дрона прикрывает только теневой HOME. Состояние сессий он держит вне git-worktree (иначе дерево было бы вечно грязным для git status) и, как и транскрипты Claude Code, само оно не подчищается.

Третий харнесс = файл рядом с этими двумя плюс строка в реестре (src/executors/index.ts). Если для него пришлось тронуть общий код — значит, чинить надо интерфейс, а не общий код; на это и стоит contract.test.ts.

Служебные файлы роя в worktree

Кое-что рой кладёт прямо в рабочее дерево дрона: .swarm-mcp.json (конфиг MCP-сервера роя, в нём токен прогона) и .swarm-task/ (вложения задачи). Ваш .gitignore про них знать не обязан — это файлы роя, а не проекта, и рой прячет их сам, на каждом подготовленном worktree (TASWM-372):

• паттерны уезжают в .git/info/exclude — локальный exclude вашего клона, файлы в репозиторий не коммитятся, а сам репозиторий при этом не тронут;
• pre-commit/pre-push рвут операцию, если служебный файл всё-таки оказался в индексе (git add -f, файл приехал закоммиченным с ветки). Хуки ставятся строго пер-worktree (git config --worktree core.hooksPath, каталог — .git/worktrees/<id>/swarm-hooks) и в конце вызывают ваш прежний хук: husky и прочая дисциплина репозитория продолжают работать.

Список файлов — один, src/swarmFiles.ts; оттуда же берут имена те, кто их пишет. Кладёте в worktree что-то новое — впишите туда, и оно спрячется само.

Windows

Рой работает на Windows, но рекомендуемый способ — WSL2: там он ведёт себя ровно как на macOS/Linux, и swarm install работает так же, как на Linux. На нативной Windows та же команда говорит это вслух, делает свою часть (пакеты npm — они кросс-платформенные; системных зависимостей Chromium там нет) и не выдаёт линуксовых советов: sudo apt-get пользователю PowerShell не поможет.

Нативная Windows проверена вживую 02–03.08.2026 (Windows 11 Pro), рой поднимается и доводит задачи до конца, но у неё есть особенности:

• ps и lsof на Windows нет. Демон берёт снапшот процессов через Get-CimInstance Win32_Process (нужен PowerShell в PATH) и гасит дерево процессов через taskkill /T /F — групповых сигналов (kill(-pid)) Windows не умеет. У Win32_Process нет рабочего каталога процесса, поэтому процессы worktree опознаются по командной строке и по родству, а не по cwd, — детект чуть грубее.
• Длинные пути. Демон включает core.longpaths=true для рабочего репозитория сам. Без него git worktree remove падает Filename too long на node_modules.
• Бинарь claude. spawn на Windows ищет исполняемый файл по PATHEXT, поэтому bash-обёртка ~/bin/claude без расширения ему не видна. Демон сам находит claude.exe в %APPDATA%\Claude\claude-code\<версия> и в MSIX-копии под %LOCALAPPDATA%\Packages\Claude*. Нестандартная установка — укажите путь явно: SWARM_CLAUDE_BIN=D:\path\to\claude.exe.
• Docker Desktop вызовы docker ps может подвешивать, пока поднимается, — и вместе с ними тик демона. Для тестов на фейк-базе Docker дронам не нужен вовсе.

Лимит дронов: машина + проект

maxDrones — двухуровневый: личный (uiPrefs.swarm.maxDrones в профиле — «Рой» в настройках Taskless) — жёсткий потолок дронов этой машины, физическая ёмкость железа; проектный (swarmConfig.maxDrones, set_project_swarm) — квота внутри машинного капа, сколько из этих дронов одновременно может занять один проект. Оба подхватываются без рестарта демона.

Демон = машина: кап и счётчик активных дронов считаются по Taskless-аккаунту, которым демон залогинен (swarm login), а не по физическому железу напрямую. Если поднимаете второй демон на выделенном сервере отдельного проекта и не хотите, чтобы он делил кап с ноутбуком оператора — заводите ему отдельный Taskless-аккаунт и логиньте под ним. Один и тот же аккаунт на двух машинах делит один кап и один счётчик дронов (они реально соревнуются за слоты); разные аккаунты — полностью независимые капы, без единой правки конфига.

Несколько машин: закрепить прогон

Один аккаунт может держать демона на нескольких машинах (ноутбук + рабочая станция). Очередь у них общая: свободный прогон берёт тот демон, у которого репозиторий прогона есть локально. Когда работа обязана идти именно на конкретной машине — закрепите прогон за ней:

swarm hosts                                  # какие машины есть: имя, пульс, id
swarm spawn PRJ-42 --host Hunt-gaming-laptop # закрепить прогон за машиной (имя или id)

Закреплённый прогон возьмёт только демон этой машины — остальные его не видят. Если машина не на связи, прогон её ждёт и на другую не уезжает: это осознанный выбор оператора, а не сбой (в дашборде /swarm видно, какую машину он ждёт и что она молчит). Снять закрепление — выбрать «Любая машина» в модалке прогона или swarm_run_upsert{runId, hostId:null}.

Без --host всё работает как раньше: прогон свободен, а машина, которая его взяла и потом замолчала на 15 минут, отпускает его обратно в очередь.

Логи с удалённой машины

Когда дрон спотыкается, нужен сырой лог — а он лежит файлом на машине демона (~/.taskless-swarm/run-logs/<ключ прогона>/ — прод-cuid либо local-<instance>-<номер>, TASWM-419; каталоги-номера прошлых жизней демона демон при старте уносит в run-logs/legacy/). Просить владельца машины показать хвост больше не нужно: MCP-тулы отдают его сами, независимо от того, где выполнялся прогон.

swarm_run_log(runId, lines)      # хвост лога прогона (stdout + stderr дрона)
swarm_daemon_log(hostId, lines)  # хвост лога самого демона — когда дрон не стартовал вовсе

Прод к демону за домашним роутером не стучится, поэтому запрос уезжает командой в ответе на пульс — ответ приходит со следующим пульсом (~15с), тул ждёт его сам. Отдаётся только ХВОСТ (потолок и по строкам, и по байтам) и только транзитом: в базе трекера лог не оседает, строка обмена умирает на чтении. Чужие логи недоступны — и запрос, и доставка скоупятся владельцем машины.

Лог самого демона заводится сам: фоновый swarm start пишет в ~/.taskless-swarm/overmind.log. Свой путь — SWARM_DAEMON_LOG. Ротация идёт и при старте, и на живом демоне (он рассчитан на недели без рестарта, и раньше у такого процесса ротация не срабатывала ни разу): перерос потолок — содержимое уезжает в .1, прошлые поколения сдвигаются, старые сверх лимита удаляются. Ручки — SWARM_DAEMON_LOG_MAX_BYTES (по умолчанию 16 МБ), SWARM_DAEMON_LOG_KEEP (2 поколения), SWARM_DAEMON_LOG_CHECK_MS (как часто демон смотрит на размер, 1 мин). Смотреть на месте:

swarm logs            # хвост лога демона (по умолчанию 200 строк)
swarm logs -n 50 -f   # следить за новыми строками
swarm log <runId>     # это ДРУГОЕ: лог конкретного прогона

Запустили с --foreground — вывод идёт в терминал, и файла не будет: тогда за него отвечает тот, кто перенаправил (systemd, docker, tee).

Правообладатель и лицензия

© 2026 Ilya Smurov. Проприетарное коммерческое ПО — см. LICENSE. Использование — только в связке с сервисом Taskless. Вопросы: [email protected]