Baton

<p align="center">
  <img src="assets/baton.svg" width="88" alt="Baton" style="border-radius: 20px">
</p>

<h1 align="center">Baton</h1>

<p align="center">
  <strong>Run, hot-reload, check and screenshot your apps from any coding agent.</strong><br>
  Flutter, Next.js, Vite, React Native / Expo, and native iOS and Android, from a terminal, the Baton app, or any MCP client.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/baton-run"><img alt="npm version" src="https://img.shields.io/npm/v/baton-run?color=111827&label=npm%20baton-run"></a>
  <a href="https://github.com/kanumuri9593/Baton/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/kanumuri9593/Baton/actions/workflows/ci.yml/badge.svg"></a>
  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-0ea5e9"></a>
  <a href="https://nodejs.org/"><img alt="Node >= 24" src="https://img.shields.io/badge/node-%3E%3D24-339933"></a>
  <a href="https://registry.modelcontextprotocol.io/v0/servers?search=io.github.kanumuri9593/baton"><img alt="MCP Registry: io.github.kanumuri9593/baton" src="https://img.shields.io/badge/MCP%20Registry-io.github.kanumuri9593%2Fbaton-7c3aed"></a>
</p>

<p align="center">
  <a href="https://kanumuri9593.github.io/Baton/">Website</a> ·
  <a href="docs/clients.md">Set up your agent</a> ·
  <a href="AGENTS.md">Agent notes</a> ·
  <a href="docs/pdf/">PDF guides</a> ·
  <a href="docs/token-study/">Token study</a> ·
  <a href="CHANGELOG.md">Changelog</a>
</p>

<p align="center">
  <a href="https://insiders.vscode.dev/redirect/mcp/install?name=baton&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22baton-run%22%5D%7D"><img alt="Install in VS Code" src="https://img.shields.io/badge/VS_Code-Install_Baton-0098FF?logo=visualstudiocode&logoColor=white"></a>
  <a href="https://insiders.vscode.dev/redirect/mcp/install?name=baton&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22baton-run%22%5D%7D&quality=insiders"><img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-Install_Baton-24bfa5?logo=visualstudiocode&logoColor=white"></a>
  <a href="https://cursor.com/en/install-mcp?name=baton&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJhdG9uLXJ1biJdfQ%3D%3D"><img alt="Add Baton to Cursor" src="https://img.shields.io/badge/Cursor-Add_Baton-111827?logo=cursor&logoColor=white"></a>
</p>

<p align="center">
  <img src="assets/baton-check.gif" width="760" alt="An agent edits a web page, check_change reports NOT OK with the browser console error, the agent fixes the typo and check_change reports OK with a phone screenshot">
</p>

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](https://github.com/kanumuri9593/Baton/issues)
with what broke or what you wanted.

## Quick start

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

```bash
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:

| Way | Command |
|---|---|
| Claude Code plugin | `/plugin marketplace add kanumuri9593/Baton` then `/plugin install baton@baton` |
| Codex plugin | `codex plugin marketplace add kanumuri9593/Baton` then `codex plugin add baton@baton` |
| VS Code or Cursor, one click | the install buttons at the top of this page |
| MCP server, no install | `npx -y baton-run` as the server command (pin with `baton-run@0.2.10`) |
| Pinned GitHub install | `npm install -g github:kanumuri9593/Baton#v0.2.10` |
| From source | `git clone https://github.com/kanumuri9593/Baton.git && cd Baton && npm install && npm run build` |

`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:

```json
{
  "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

| Agent | `baton setup` id | Guide |
|---|---|---|
| Claude Code (terminal, desktop app, VS Code) | `claude` (installs the plugin) | [docs/clients/claude-code.md](docs/clients/claude-code.md) |
| Codex | `codex` | [docs/clients/codex.md](docs/clients/codex.md) |
| Cursor | `cursor` | [docs/clients/cursor.md](docs/clients/cursor.md) |
| VS Code (GitHub Copilot agent mode) | `vscode` | [docs/clients/vscode.md](docs/clients/vscode.md) |
| Antigravity | `antigravity` | [docs/clients/antigravity.md](docs/clients/antigravity.md) |
| Gemini CLI | `gemini` | [docs/clients/gemini-cli.md](docs/clients/gemini-cli.md) |
| Windsurf | `windsurf` | [docs/clients/windsurf.md](docs/clients/windsurf.md) |
| Claude Desktop (chat) | manual only | [docs/clients/claude-desktop.md](docs/clients/claude-desktop.md) |

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

Printable guides to share: [quick start](docs/pdf/baton-quick-start.pdf),
[agent setup guide](docs/pdf/baton-agent-setup-guide.pdf) and [FAQ](docs/pdf/baton-faq.pdf).

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

| Button | What it does |
|---|---|
| ☰ | Show or hide that run's recent logs under its row |
| 🐞 | Debug: asks Claude to read the run's errors and logs, fix the cause and `check_change` |
| ▶ | Play: hot reload (or restart) a running app, resume a paused one, or run it again once it ends |
| ⏸ | Pause the app (macOS) |
| ⏹ | Stop. Once a run has ended this becomes ✕ dismiss |
| ⧉ | Bring that run's own simulator window (or its web page) to the front (macOS) |

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](docs/clients/claude-code.md).

## What it supports

| Framework | Hot reload (keeps state) | Restart | Notes |
|---|---|---|---|
| **Flutter / Dart** | ✅ real, via the daemon protocol | ✅ hot restart | Devices, DevTools, debug flags, screenshots (Flutter web too) |
| **Next.js, Vite, Nuxt, Astro, Remix, Angular, CRA** | HMR is automatic on save | ✅ reboots the dev server | Detects the real URL and readiness; phone, tablet and desktop sc