Baton

Baton

Run, hot-reload, check and screenshot your apps from any coding agent.

Flutter, Next.js, Vite, React Native / Expo, and native iOS and Android, from a terminal, the Baton app, or any MCP client.

= 24" src="https://img.shields.io/badge/node-%3E%3D24-339933">

Website · Set up your agent · Agent notes · PDF guides · Token study · Changelog

Baton is a local daemon that owns your running apps, with an MCP server and a CLI in front of it. Your agent starts an app on a simulator or in a browser, applies each edit with one check_change call, and gets back only what is new: the reload result, error lines, failed requests and a screenshot, with an OK / NOT OK verdict. You see the same runs in your terminal, in the Baton app, and in the band above Claude Code's prompt, and you can press the same buttons. Baton reads the .vscode/launch.json, package.json, pubspec.yaml, Xcode and Gradle projects you already have.

0.2.10 is a public developer preview. Open an issue with what broke or what you wanted.

Quick start

Requires Node.js 24+ on the machine that runs your apps. macOS, Linux and Windows.

npm install -g baton-run

baton setup # adds Baton to every coding agent installed on this machine

Restart your agent (or open a new chat) and ask it to "run the app and show me a screenshot".

Other ways in:

baton setup edits only the baton entry in each tool's config, keeps a .baton-backup of every file it changes, and is safe to run again. baton setup cursor codex limits it to those tools, --dry-run previews, --remove undoes it.

Any MCP client that takes an mcpServers block:

{

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

The agent loop

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

1. inspect_project (and list_targets) with cwd set to the absolute project path.
2. boot_device if no simulator or emulator is up. With no name it lists what can boot.
3. run_target, or run_workflow for an API plus a frontend, then wait_for. wait_for accepts up to 15 minutes, enough for a first native build.
4. After every edit, check_change. It applies the edit (hot reload for Flutter, HMR for web and React Native, restart for native and plain processes) and returns only what changed.

NOT OK  console/storefront  action=none  status=running  2280ms

new errors (1): [vite] Internal server error: Unexpected token (14:2)

Failed Flutter reloads return the compiler errors, not just DevFS synchronization failed:

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

Screenshots cover iOS simulators, Android devices and web apps. For web, Baton opens the session URL in a throwaway headless Chrome, Edge or Brave (or BATON_CHROME) at viewport phone (a real 390×844 mobile layout), tablet, desktop or WIDTHxHEIGHT. Web captures are 1× by default, so a phone image is 390×844 (about 430 image tokens for a model); pass scale: 2 (--scale 2) when fine detail matters. check_change with screenshot: false returns text only but still loads a web page, so its console errors count. Simulator and device screenshots are returned at the device's own resolution.

Baton launches apps and reports evidence. It does not tap the UI or judge screenshots: a capture means an image was written, not that the screen is right. Pair it with Playwright MCP, Chrome DevTools MCP or a device-control MCP when a flow needs input.

29 tools: 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 and dashboard_action (the buttons on the live card that show_dashboard draws in hosts that support MCP Apps). Each carries MCP hints, so clients that honour them can skip the prompt for the 16 read-only tools.

Supported agents

Agents without MCP can shell out to the same CLI. Every command exits non-zero on failure, and baton check --json gives the same verdict as check_change. Full agent notes: AGENTS.md. Crawler summary: llms.txt.

Printable guides to share: quick start, agent setup guide and FAQ.

In Claude Code: the Baton band

The plugin draws Baton above the prompt while anything runs, in the terminal and in the desktop app. One row per run, with its device or URL, status, CPU and memory, and icon buttons:

The header has ＋ (new run: puts /baton:run in the prompt) and the same ▶ ⏸ ⏹ ⧉ for every run at once. Bring all raises every device's window. /baton opens the same workspace in a side pane with longer logs. The band and pane read the same daemon as the MCP tools, so a run started by Claude, the CLI or the Baton app shows up everywhere. Details: docs/clients/claude-code.md.

What it supports

Capabilities are reported honestly. A Vite session does not claim Flutter's stateful hot reload, so the control panel greys the button out and agents get a clear refusal instead of a silent no-op.

Where targets come from

Baton reads what you already have. No new config file is required.

• .vscode/launch.json, read but never modified, so your IDE keeps working
• .claude/launch.json, same format
• package.json: dev, start, serve and storybook scripts, with the package manager taken from your lockfile
• pubspec.yaml: Flutter projects with no launch.json still get a default
• Xcode: .xcodeproj / .xcworkspace, shared schemes, Podfile, or Package.swift
• Gradle: settings.gradle(.kts), the wrapper, application modules, or a lone AndroidManifest.xml

A nested ios/ or android/ folder picked on its own is a native target. Picking the Flutter or React Native root still runs the framework, which is what hot-reloads. Native sessions build, install and launch on the device you pick, then follow the app log. Restart rebuilds and relaunches.

baton init writes a .vscode/launch.json from what it detects (--claude for .claude/launch.json). See examples/ for small launch configs.

The CLI

baton list                                  # every ta