API ВЕГА
English

Baton

Запускайте приложения, применяйте горячую перезагрузку, проверяйте их и делайте скриншоты из любого агента для программирования.

Flutter, Next.js, Vite, React Native / Expo, а также нативные приложения для iOS и Android — из терминала, приложения Baton или любого MCP-клиента.

Сайт · Настройка агента · Инструкции для агентов · Руководства в формате PDF · Исследование токенов · История изменений

Baton — локальный демон, который управляет запущенными приложениями. Для работы с ним используются MCP-сервер и CLI.

Агент запускает приложение в симуляторе или браузере, применяет каждое изменение одним вызовом

check_change и получает только новые сведения: результат перезагрузки, строки с ошибками, неудачные

запросы и скриншот, а также итоговый статус OK / NOT OK. Вы можете видеть те же запуски в терминале,

приложении Baton и панели над строкой ввода Claude Code и нажимать те же кнопки. Baton считывает

уже существующие у вас файлы .vscode/launch.json, package.json, pubspec.yaml, а также проекты Xcode и Gradle.

Версия 0.2.10 — публичная предварительная версия для разработчиков. Сообщите о проблеме

и расскажите, что не работает или каких возможностей вам не хватает.

Быстрый старт

На компьютере, где запускаются приложения, требуется Node.js 24+. Поддерживаются macOS, Linux и Windows.

npm install -g baton-run
baton setup          # adds Baton to every coding agent installed on this machine

Перезапустите агента (или откройте новый чат) и попросите его: «Запусти приложение и покажи скриншот».

Другие способы установки:

СпособКоманда
Плагин Claude Code/plugin marketplace add kanumuri9593/Baton затем /plugin install baton@baton
Плагин Codexcodex plugin marketplace add kanumuri9593/Baton затем codex plugin add baton@baton
VS Code или Cursor, установка одним щелчкомкнопки установки в верхней части этой страницы
MCP-сервер, без установкиnpx -y baton-run в качестве команды сервера (зафиксируйте версию через baton-run@0.2.10)
Установка с закреплённой версией GitHubnpm install -g github:kanumuri9593/Baton#v0.2.10
Сборка из исходного кодаgit clone https://github.com/kanumuri9593/Baton.git && cd Baton && npm install && npm run build

baton setup изменяет только запись baton в конфигурации каждого инструмента, сохраняет резервную копию

.baton-backup для каждого изменённого файла и может безопасно запускаться повторно. Команда baton setup cursor codex

ограничивает настройку этими инструментами, --dry-run показывает предварительный результат, а --remove отменяет изменения.

Подойдёт любой MCP-клиент, поддерживающий блок mcpServers:

{
  "mcpServers": {
    "baton": { "command": "npx", "args": ["-y", "baton-run@0.2.10"] }
  }
}

Цикл работы агента

inspect_project → boot_device → run_target → wait_for → edit → check_change → fix → check_change

  • Запустите inspect_project (и list_targets), указав в cwd абсолютный путь к проекту.

  • Используйте boot_device, если симулятор или эмулятор ещё не запущен. Если не указать имя, команда покажет доступные варианты запуска.

  • Выполните run_target или run_workflow для API вместе с frontend, а затем вызовите wait_for. wait_for

    принимает значение до 15 минут — этого достаточно для первой нативной сборки.

  • После каждого изменения вызывайте check_change. Команда применяет изменение (hot reload для Flutter, HMR для web

    и React Native, перезапуск для нативных приложений и обычных процессов) и возвращает только новые сведения.

NOT OK  console/storefront  action=none  status=running  2280ms
new errors (1):
  [vite] Internal server error: Unexpected token (14:2)

Если перезагрузка Flutter завершается с ошибкой, Baton возвращает ошибки компилятора, а не только сообщение DevFS synchronization failed:

lib/main.dart:419:19: Error: Expected ';' after this.

Скриншоты можно делать в симуляторах iOS, на устройствах Android и в web-приложениях. Для web Baton открывает URL

сеанса в отдельном экземпляре headless Chrome, Edge или Brave (либо BATON_CHROME) с параметром viewport:

phone (реальный мобильный макет размером 390×844), tablet, desktop или WIDTHxHEIGHT.

По умолчанию снимки web-страниц создаются в масштабе 1×: изображение для телефона будет размером 390×844

(около 430 image-токенов для модели). Если важны мелкие детали, укажите scale: 2 (--scale 2). Вызов check_change с параметром

screenshot: false возвращает только текст, но всё равно загружает web-страницу, поэтому ошибки в консоли учитываются.

Скриншоты симуляторов и устройств возвращаются в исходном разрешении устройства.

Baton запускает приложения и сообщает результаты проверок. Он не взаимодействует с интерфейсом и не оценивает скриншоты:

сохранение снимка означает лишь, что изображение создано, а не то, что экран отображается правильно. Если сценарию нужно взаимодействие,

дополните Baton инструментами Playwright MCP, Chrome DevTools MCP или MCP для управления устройством.

29 инструментов: inspect_project, list_targets, list_sessions, list_checkouts,

list_devices, boot_device, run_target, run_workflow, check_change, hot_reload,

hot_restart, stop_session, forget_session, wait_for, read_logs, session_summary,

screenshot, set_debug_flag, diagnose, list_network_requests, get_network_request,

clear_network_requests, read_launch_config, write_launch_config, run_proof,

list_proofs, list_run_history, show_dashboard и dashboard_action (кнопки на активной карточке,

которую show_dashboard отображает в хостах с поддержкой MCP Apps). Каждый инструмент содержит подсказки MCP,

поэтому клиенты, учитывающие их, могут не запрашивать подтверждение для 16 инструментов только для чтения.

Поддерживаемые агенты

АгентИдентификатор baton setupРуководство
Claude Code (терминал, настольное приложение, VS Code)claude (устанавливает плагин)docs/clients/claude-code.md
Codexcodexdocs/clients/codex.md
Cursorcursordocs/clients/cursor.md
VS Code (режим агента GitHub Copilot)vscodedocs/clients/vscode.md
Antigravityantigravitydocs/clients/antigravity.md
Gemini CLIgeminidocs/clients/gemini-cli.md
Windsurfwindsurfdocs/clients/windsurf.md
Claude Desktop (чат)только вручнуюdocs/clients/claude-desktop.md

Агенты без MCP могут запускать те же команды через shell. При ошибке любая команда завершается с ненулевым кодом выхода,

а baton check --json возвращает тот же итоговый статус, что и check_change. Полные инструкции для агентов:

AGENTS.md. Сводка для поисковых роботов: llms.txt.

Руководства для печати и распространения: быстрый старт,

руководство по настройке агента и часто задаваемые вопросы.

Baton в Claude Code: панель запусков

Плагин отображает панель Baton над строкой ввода, пока что-либо запущено, — и в терминале, и в настольном

приложении. Для каждого запуска показывается отдельная строка с устройством или URL, статусом, загрузкой CPU и памяти,

а также кнопками:

КнопкаДействие
☰Показать или скрыть последние записи журнала этого запуска под соответствующей строкой
🐞Отладка: просит Claude изучить ошибки и журналы запуска, устранить причину и вызвать check_change
▶Запуск: применить hot reload (или перезапустить) работающее приложение, возобновить приостановленное или запустить снова завершившееся
⏸Приостановить приложение (macOS)
⏹Остановить. После завершения запуска кнопка меняется на ✕ и закрывает его
⧉Переместить окно симулятора этого запуска (или его web-страницу) на передний план (macOS)

В заголовке есть кнопка ＋ (новый запуск: добавляет /baton:run в строку ввода), а также те же кнопки ▶ ⏸ ⏹ ⧉ для всех

запусков сразу. Кнопка Bring all выводит на передний план окна всех устройств. Команда /baton открывает ту же рабочую область

в боковой панели с более подробными журналами. Панель и боковая область используют тот же демон, что и инструменты MCP,

поэтому запуск, начатый через Claude, CLI или приложение Baton, отображается везде. Подробности:

docs/clients/claude-code.md.

Поддерживаемые технологии

ФреймворкГорячая перезагрузка (с сохранением состояния)ПерезапускПримечания
Flutter / Dart✅ настоящая, через протокол демона✅ горячий перезапускУстройства, DevTools, флаги отладки, снимки экрана (в том числе для Flutter web)
Next.js, Vite, Nuxt, Astro, Remix, Angular, CRAHMR выполняется автоматически при сохранении✅ перезапускает сервер разработкиОпределяет фактический URL и готовность; снимки экрана на телефонах, планшетах и компьютерах
React Native / ExpoFast Refresh выполняется автоматически✅ отправляет команду перезагрузки клиентам разработкиИспользует сокет сообщений Metro
Native iOS (Xcode)—✅ пересобирает, переустанавливает и запускаетСобирает проект для выбранного симулятора, устанавливает и запускает приложение, отслеживает журналы, делает снимки экрана
Native Android (Gradle)—✅ пересобирает, переустанавливает и запускаетВыполняет installDebug, запускает активность приложения, отслеживает logcat, делает снимки экрана
Всё остальное—✅ завершает процесс и запускает его зановоЛюбой скрипт из launch.json или package.json

Возможности указываются честно. Например, сессия Vite не заявляет о горячей перезагрузке с сохранением состояния, доступной во Flutter. Поэтому кнопка в панели управления будет неактивной, а агенты получат понятное сообщение об отказе вместо того, чтобы команда просто ничего не сделала.

Откуда берутся цели запуска

Baton использует уже имеющиеся у вас настройки. Создавать новый файл конфигурации не нужно.

  • .vscode/launch.json: Baton читает этот файл, но не изменяет его, поэтому IDE продолжает работать как прежде

  • .claude/launch.json: файл того же формата

  • package.json: скрипты dev, start, serve и storybook; менеджер пакетов определяется по lock-файлу

  • pubspec.yaml: для проектов Flutter без launch.json также создаётся цель запуска по умолчанию

  • Xcode: .xcodeproj / .xcworkspace, общие схемы, Podfile или Package.swift

  • Gradle: settings.gradle(.kts), wrapper, модули приложения или отдельный AndroidManifest.xml

Если выбрать вложенную папку ios/ или android/, она станет нативной целью. Если выбрать корневую папку Flutter или React Native, запустится фреймворк — именно он обеспечивает горячую перезагрузку. Нативные сессии собирают и запускают приложение на выбранном устройстве, затем отслеживают журналы приложения. Перезапуск пересобирает и повторно запускает приложение.

Команда baton init создаёт .vscode/launch.json на основе обнаруженных настроек (--claude создаёт .claude/launch.json). Небольшие примеры конфигураций запуска приведены в разделе examples/.

Интерфейс командной строки

baton list                                  # every target, and where it came from
baton run "iOS Simulator (DEV)"             # names match on any unambiguous substring
baton run "iOS Simulator (DEV)" --branch origin/main
baton ps                                    # what's running
baton logs dev -f                           # follow output
baton check webapp --viewport phone         # did my edit break anything?
baton reload --all
baton stop --all
baton devices --all                         # connected devices, plus every one you could boot
baton boot "iPhone 17 Pro Max"              # start a simulator that isn't running
baton add ~/code/storefront                 # watch another project too
baton doctor                                # sources, blockers, nested projects, guidance
baton app                                   # the control panel

Команда baton help выводит список всех команд.

Одновременная работа с несколькими приложениями и проектами

Запустите API и консоль в нужном порядке одной командой:

baton workflow examples/workflow-lab/workflow.json

В результате будут указаны идентификаторы сессий, готовность, URL и подробная информация об ошибках. MCP-агенты используют команду run_workflow. Попробуйте лабораторную работу с двумя проектами, для которой не нужны зависимости.

Демон не привязан к одной директории. Команда baton add добавляет для отслеживания ещё один проект; после этого в панели управления для каждого проекта появляется отдельная боковая панель, а также пункт Все. Идентификаторы сессий привязаны к проекту (storefront/npm-dev, api/npm-dev), поэтому в двух проектах одновременно могут работать команды npm dev. Сессиями управляет демон, поэтому закрытие терминала не останавливает приложение.

Устройства, которые ещё не запущены

connected
  ● iPhone 17 Pro                48F0A0D1-…  ios (emulator)
  ● sdk gphone16k arm64          emulator-5556  android (emulator)

bootable
  ○ iPhone 17 Pro Max            3237F94B-…  ios  iOS 26.5
  ○ iPad mini (A17 Pro)          51470177-…  ios  iOS 26.5
  ○ Pixel 10 Pro                 Pixel_10_Pro  android

В списке эмуляторов Flutter все iPhone и iPad объединены в одну запись, поэтому Baton обращается напрямую к simctl. Команда baton boot "iPad mini" запускает симулятор, ожидает, пока Flutter обнаружит его, и выводит идентификатор устройства, на котором можно запустить приложение.

Работа с веткой без переключения Git

Выберите локальную или удалённую ветку — Baton создаст Git worktree в ~/.baton/worktrees, скопирует из вашей папки секреты и конфигурацию (но не build/ и node_modules) и запустит приложение из этой копии. Ваша ветка, stash и редактор останутся без изменений. Можно также подключить уже существующие worktree — например, папки, в которых работают агенты; горячая перезагрузка будет учитывать изменения в этой папке.

baton run "iOS Simulator (DEV)" --branch origin/main
baton run "iOS Simulator (DEV)" --checkout ~/wt/agent-a
baton checkouts

Проверки перед запуском

В конфигурациях часто указываются файлы, исключённые из Git. Сначала Baton проверяет их наличие и не запускает приложение, если чего-то не хватает:

✗ "iOS Simulator (DEV / dev flavor)" cannot run yet:
  missing config/secrets.local.json — copy config/secrets.local.template.json to config/secrets.local.json

Команда baton list аналогичным образом помечает цели, запуск которых заблокирован. Флаг --force позволяет запустить их в любом случае.

Данные с разных устройств

baton proof "Local lab" --branch main --devices "iPhone 17 Pro" --appearance light,dark

В пакеты отчётов входят журналы, снимки экрана и сводки по сети. Подробнее см. в руководстве по запуску и проверке. Начать можно с лабораторной работы Flutter, для которой не нужны учётные данные.

Трассировка запросов к серверной части

В целях запуска Node можно задать "batonTrace": true, чтобы собирать локальные метаданные OpenTelemetry для HTTP/HTTPS и fetch. Команда baton diagnose (а также diagnose в MCP) выводит краткую сводку ошибок по сессиям; команда baton diagnose --all позволяет проследить один запрос через несколько проектов Node. Подробнее см. в разделе локальная трассировка запросов к серверной части.

Приложение Baton

baton app

Для каждой сессии отображается отдельная компактная строка: статус, команды перезагрузки, перезапуска и остановки, журналы, ссылки на URL приложения и DevTools. Нажмите r, чтобы выполнить горячую перезагрузку всех видимых сессий, или R — чтобы выполнить горячий перезапуск. Приложение не нужно скачивать из App Store.

  • macOS: плавающая панель запуска и значок в строке меню. Панель остаётся поверх полноэкранного терминала и не перехватывает фокус; значок в строке меню показывает число активных сессий. При первом запуске небольшой хост на AppKit собирается из исходного кода в hud/. Для этого нужны Xcode или Command Line Tools; если они не установлены, Baton откроется в браузере.

  • Linux и Windows (а также запуск baton app --browser): та же страница открывается в окне браузера, оформленном как приложение. Демон предоставляет её через loopback, без внешних запросов.

Настройки: docs/app-settings.md. Команда baton hud сохранена как псевдоним для совместимости.

Принцип работы

.vscode/launch.json ─┐
package.json  ───────┤
pubspec.yaml  ───────┼─► detect ─► daemon ─► one session per target
Xcode / Gradle  ─────┘                │       (flutter | web-dev | react-native | ios | android | process)
                                      │
                     WebSocket + POST /rpc on 127.0.0.1
                          ├── Baton app  (native panel on macOS, browser elsewhere)
                          ├── baton      (any terminal)
                          └── baton-mcp  (any agent)

Один демон управляет всеми сессиями, поэтому сессия, запущенная в терминале, видна и в панели управления, и вашему агенту. Демон привязывается к 127.0.0.1 и записывает в ~/.baton/daemon.json (режим 0600) свой порт и токен; клиенты считывают их и проходят аутентификацию.

Для Flutter сессии запускаются как дочерние процессы flutter run --machine, а каждая команда управления отправляется отдельным запросом через документированный JSON-протокол (app.restart, app.stop, app.callServiceExtension). Учитывается версия FVM: если в проекте задан SDK в .fvm/flutter_sdk, используется именно он. Подробнее см. в docs/architecture.md.

Статус

По состоянию на версию 0.2.3 Baton протестирован на крупном промышленном приложении Flutter с 3 692 библиотеками: горячая перезагрузка занимает 87 мс, горячий перезапуск — 359 мс. Одновременно можно использовать три симулятора, а три проекта (Flutter, Vite и обычный worker) — размещать рядом в одной панели управления. Адаптер Flutter реализован наиболее полно. Адаптеры Web и React Native поддерживают запуск, перезапуск, журналы и определение URL.

Устранение неполадок

  • ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING: у вас установлена старая версия baton-run@0.2.0. Выполните команду:

npm uninstall -g baton-run && npm install -g baton-run.

  • Агент не видит Baton: после выполнения baton setup перезапустите приложение или откройте новый чат, затем

ознакомьтесь с руководством для нужного инструмента в документации по клиентам.

  • Не удаётся сделать скриншоты веб-страниц: установите Chrome, Chromium, Edge или Brave либо укажите путь к исполняемому файлу браузера в переменной BATON_CHROME.

  • Другая проблема: выполните baton doctor или /baton:doctor в Claude Code.

Если не указать тег версии в github:kanumuri9593/Baton, будет использоваться ветка main. Рекомендуем указать #v0.2.10 или установить пакет командой npm install -g baton-run.

Участие в разработке

npm install
npm test          # portable tests, no simulator required
npm run typecheck

См. CONTRIBUTING.md. О проблемах безопасности сообщайте конфиденциально, следуя инструкциям в

SECURITY.md. В проекте действует Кодекс поведения.

Значок приложения и векторные изображения находятся в assets/; команда npm run icons создаёт PNG-файлы всех распространённых размеров и файл .icns для macOS.

Лицензия

MIT. Автор и сопровождающий проекта — Yeswanth Varma Kanumuri.