pitbox

Run, drive and debug apps on emulators, simulators and devices from one MCP server — fast and token-lean.

pitbox gives a coding agent (and you) one tool for the whole local loop: the stand your app talks to, the devices it runs on, and the checks that tell you what is broken. It works with any framework; React Native gets extra reach inside the app.

• Phones, foldables, tablets, TVs, watches, XR headsets, glasses and cars — Android emulators and devices, Apple simulators, and web apps in a browser, behind the same tools.

• Answers an agent can afford — the screen as short lines with refs, actions that wait for the UI to settle and reply with what changed, images only on request.

• Flows — a line-per-step script run by the daemon: a whole pass in one call, one verdict.

• Checks instead of screenshots — is the video playing, does the screen match its baseline, can the D-pad reach everything, which function made the frame janky.

• The stand — services, mocks and backend states started from one config and kept warm between sessions.

• Inside a React Native app with no app code — fresh code or stale, the network log and rules, the console, eval and logpoints, hot updates, React renders.

Quick start

yarn add -D @veksa/pitbox
npx pitbox init          # writes pitbox.config.ts from what it finds in the project

Add the MCP server to the project's .mcp.json:

{"mcpServers": {"pitbox": {"command": "npx", "args": ["pitbox", "mcp"]}}}

Or drive it from the shell:

pitbox up                # the stand: services, dev server
pitbox boot              # the configured emulator, ports forwarded
pitbox open              # launch the app
pitbox snapshot          # the screen as text
pitbox run smoke         # flows/smoke.flow, one verdict

A config by hand:

// pitbox.config.ts
import {defineConfig} from '@veksa/pitbox';

export default defineConfig({
  app: {android: 'com.example.app', apple: 'com.example.app'},
  android: {avd: 'Pixel_8'},
  services: {
    db: {start: 'docker compose up -d db', stop: 'docker compose stop db', health: 'docker:db'},
    api: {start: 'yarn --cwd server start', health: 'http://localhost:3000/health', expose: 3000, dependsOn: ['db']},
  },
  devserver: {adapter: 'metro', root: 'mobile', bytecode: true},
});

Related MCP server: vibeview

Documentation

Contributing

See CONTRIBUTING.md.

License

MIT