Devloop

Browser control + dev-server logs on one correlated timeline — for AI agents and humans.

---

A unified dev-loop tool: it drives a browser and your dev server, pushing both sides into one timestamped buffer so you can correlate a browser console error with the backend stack trace from the same moment. It runs two ways from a shared core:

• Headless (stdio) — drives Chrome via Puppeteer, served over stdio. The lightweight mode Claude Code spawns per session. Run devloop-mcp daemon to instead serve one shared, long-running instance over HTTP/SSE that many agents/sessions connect to (see Daemon mode).
• Cockpit (Electron) — a single desktop window: tabbed browser panes (embedded WebContentsViews driven via CDP) with a browser bar (back/forward/reload + address) beside a collapsible side panel that toggles between logs and a repro builder. Project picker, auto-navigate, pop-out targets. The renderer is React 19 + Tailwind v4 + Radix + lucide-react. Serves the same tools over HTTP.

Because every event (browser console/network/page-errors and server stdout/stderr) shares one monotonic clock, get_logs_around / repro return a correlated, cross-source slice of the timeline.

Native targets — Expo / React Native (iOS + Android)

The cockpit also drives Expo/React Native projects, not just web. Open a native project and you get one pane with a Web · iOS · Android target switcher, a bundler toggle (Metro) separate from a Build button (expo run:ios / expo run:android, with @expo/fingerprint staleness detection), and:

• JS console + errors over CDP via Metro's Hermes inspector (both platforms) — with source-mapped stacks (your bundled index.bundle:1:… resolves to original .tsx).
• RN network capture — an injected XMLHttpRequest hook turns the app's fetch/XHR traffic into the same network timeline rows as web (so get_network / export_har / the network chip work for native too).
• Native device logs merged onto the timeline as a native source — iOS simctl log stream, Android logcat.
• A live, interactive device embedded in the pane — iOS via serve-sim (MJPEG, tap/scroll/type), Android via Expo's serve-emu (scrcpy H.264, up to 60fps, with tap/swipe/scroll/type). Screenshots on both.
• Agent-drivable interactions — browser_snapshot reads the native accessibility tree (iOS via idb's UIKit a11y tree; Android via uiautomator dump) and browser_click/type/scroll/press drive the device by an element's pt:x,y ref (from the snapshot) or its label — replayable through repro, openable over MCP via native_open / native_build. The same agent tools as web, mapped onto native.

All of it lands on the same correlated timeline, app-scoped — the web dev-loop experience, for a native app. (macOS + Apple Silicon for the embedded iOS simulator; Android works wherever the Android SDK + an emulator do.)

iOS interactions need [idb](https://fbidb.io): brew install facebook/fb/idb-companion and pipx install fb-idb (use Python <3.14 — newer Python breaks fb-idb). Android interactions need the Android SDK platform-tools (adb) + a booted emulator. The cockpit's Settings → native readiness runs a per-platform preflight (iOS: idb · companion · booted sim; Android: adb · booted device) and shows the exact fix for anything missing; observation (logs/screenshots) works without the interaction tooling.

serve-sim is vendored into the cockpit and run via Electron's own Node, so the embedded simulator works out of the box — offline, no `bun`/`node`/`npx` or first-run fetch. (Running from source uses the copy in node_modules instead.)

Architecture

Three transports expose one shared core, which drives one of several substrates (a real browser, or — in the cockpit — a native device). Everything pushes onto a single timestamped timeline.

%%{init: {"flowchart": {"wrappingWidth": 700}}}%%

flowchart TD clients[" MCP clients Claude Code · agents · mcporter"] clients --> stdio & daemon & cockpit

stdio[" stdio spawned per session "] daemon[" daemon HTTP/SSE · one shared instance "] cockpit[" cockpit HTTP/SSE · Electron app "]

stdio --> mcp daemon --> mcp cockpit --> mcp mcp([" MCP Server stdio transport, or HTTP/SSE for the daemon + cockpit "]) mcp --> core

core[" shared core · transport- and substrate-agnostic the MCP tool layer + one unified, correlated timeline"]

core --> iface([" IBrowserController · IBrowserManager · ITargetController capability-gated by the active target "]) iface --> pup & elec & rn

pup[" web · Puppeteer / Chrome stdio + daemon "] elec[" web · Electron CDP panes cockpit · per-project partitions "] rn[" native · React Native (Hermes) JS + network over Metro CDP "]

rn -->|"idb / adb"| nd[" NativeDriver iOS idb · Android adb taps · snapshot · screens · logs"]

The tool layer never knows what's behind it — Puppeteer or Electron, stdio or HTTP, web page or native app. It's wired once at startup. The browser sits behind a single IBrowserController interface; the cockpit's pane manager implements the richer IBrowserManager (multiple panes, delegating browser_* to the active one — or to the native controller when an iOS/Android target is open). A capability layer gates tools by the active target, so an agent gets a clear message instead of a substrate error.

stdout is reserved for the MCP protocol in stdio mode; all human-facing output goes to stderr.

The layers

• Transports — three entrypoints over two protocols: stdio (one server per session) and HTTP/SSE (the long-running daemon, and the cockpit). All build the same MCP server bound to the tool layer; only the HTTP transports are multi-client (each connecting client gets its own session, one shared backend).
• Shared core — the tool layer (the MCP tools + a capability-gated dispatcher) over one unified, correlated timeline (server output, browser console/network/errors, native logs), backed by a separate full-capture network ring. The cross-cutting features the tools expose — a project registry, error diagnostics, source-map resolution, HAR export, and bug-report bundles — live here too.
• Browser substrates — a shared controller interface with two web implementations (Puppeteer/Chrome for headless; Electron `WebContentsView` panes over CDP in the cockpit) and a native one (React Native over Hermes/Metro). Shared page-action + accessibility-snapshot logic and device/throttle emulation sit above them.
• Native targets — an RN controller (JS/errors/network over Metro CDP) delegates taps + snapshots to a `NativeDriver` (idb on iOS, adb on Android); native logs (simctl / logcat), screenshots + live mirrors, build orchestration (expo run), and a readiness preflight round it out.
• State & isolation — an on-disk registry (projects / session / panes), per-project session partitions, and Chrome-extension management.
• Cockpit (Electron) — the desktop shell: a pane manager (per-project partitions, native routing), the React UI (timeline, browser bar, repro builder, target switch, Android mirror), the vendored serve-sim iOS mirror and serve-emu Android stream, the in-store "Add to Devloop" injection, and the in-app updater.

Install

Headless MCP (stdio) — no clone needed, register it with Claude Code:

claude mcp add devloop --scope user -- npx -y devloop-mcp

(Published as devloop-mcp on npm; Puppeteer fetches Chromium on first install.)

Cockpit (desktop app) — grab the installer for your OS from Releases (.dmg / .exe / .AppImage). macOS ships both Apple Silicon (arm64) and Intel (x64) builds. The app checks GitHub for a newer release on launch and prompts before downloading or installing — or trigger it yourself from settings → updates → check for updates.

From source (dev) — requires bun:

bun install

bun run app # build + launch the Electron cockpit bun run start # or run the stdio MCP directly

Use it from your coding agent

Once it's registered, drop this into your `CLAUDE.md` (or any agent's rules file) so the agent drives features through Devloop and verifies them live instead of reasoning from the code alone:

## Devloop — use it for any web/mobile feature work

When you build, test, or debug a feature that runs in a browser or an Expo / React Native app, drive it through devloop instead of reasoning from the code alone. It puts the dev-server logs and the live browser/device on one correlated timeline, so you can see what actually happened.

• Start the loop: dev_start (auto-detects the dev command), then browser_navigate to the page — or native_open for an iOS/Android target.
• Act, then verify — don't assume: after a change, reproduce it with repro (a navigate/click/type sequence) and read the result. Never claim a fix works without exercising it in the running app.
• Find/target elements with browser_snapshot (returns clickable ref selectors) — prefer it over screenshots.
• When something breaks: diagnose first (groups errors + failed requests), then get_logs_around a timestamp to line up the browser console error with the matching server stack trace from the same moment. get_network / export_har for request detail.
• Definition of done: the feature is verified live in devloop — no console or page errors, the expected network calls succeeded, the UI reflects the change — not just "the code looks right."
• Setup stays yours: if a native build needs a toolchain that isn't installed, devloop tells you exactly what's missing and the command to fix it — it diagnoses, it never installs or touches your toolchain. Run the fix, then rebuild.

Register once: claude mcp add devloop --scope user -- npx -y devloop-mcp

Tools (46)

Dev server — runtime, no per-project registration needed

• dev_start({ project?, cmd?, cwd? }) — start a dev server and tee its logs. Specify it three w