devloop-supervisor

Keeps your local dev loop alive. It runs your build watches and dev servers, restarts whatever crashes, shows live logs on a status page, and gives coding agents (Claude Code, Cursor, …) an MCP endpoint to read build errors and restart processes.

Zero dependencies. Node 18.18+. Windows, macOS and Linux.

npx devloop-supervisor init      # writes devloop.config.json
npx devloop-supervisor           # status page on http://localhost:4290

Or add it to a project: npm install --save-dev devloop-supervisor, then run npx devloop-supervisor or add "dev": "devloop-supervisor" to your scripts.

---

Why

A watch (ng build --watch, tsc --watch, …) survives a compile error, but not a crash: the Node heap running out on a large build, its output folder deleted by a concurrent build, a locked file on Windows. Nothing restarts it, and you find out when the app stops picking up your changes.

devloop-supervisor:

• builds before it serves: watches start in order, and each waits for its first build, so the dev server never reads half-written output;
• restarts what dies, with backoff, and pauses a crash loop until your next save instead of spinning;
• can give the processes a larger Node heap;
• warns about competing processes, e.g. a second watch fighting over the same output folder;
• rebuilds stale outputs you aren't watching, before starting;
• writes one log file per process;
• serves a status page with live logs and Watch / Build once / Restart / Stop controls, plus desktop notifications on failure;
• exposes it all over MCP, so an agent can edit code, wait for the rebuild, and read the errors itself.

---

Configuration

devloop.config.json (found in the current folder or any parent folder):

{
  "name": "My dev loop",
  "prepare": "npm install",
  "processes": [
    {
      "id": "types",
      "kind": "watch",
      "command": "npx tsc --watch --preserveWatchOutput -p packages/shared",
      "preset": "tsc-watch",
      "sources": "packages/shared/src",
      "output": "packages/shared/dist",
      "buildOnce": "npx tsc -p packages/shared"
    },
    {
      "id": "web",
      "kind": "serve",
      "command": "npm run dev",
      "cwd": "apps/web",
      "preset": "vite",
      "port": 5173
    }
  ]
}

Processes start in the order listed. More in examples/.

Top level

Key	Default	Meaning
name	"Dev loop"	Title on the status page
port	4290	Status page, API and MCP port (bound to 127.0.0.1)
logDir	.devloop/logs	One log file per process
heapMb	none	Sets --max-old-space-size for every process (via NODE_OPTIONS)
prepare	none	Command (or { "command", "cwd", "env" }) run before anything starts
crashLimit	5	Quick crashes in a row before pausing
quickExitMs	60000	An exit sooner than this after start counts as a quick crash
firstBuildTimeoutMs	1800000	Longest wait for a process's first build before starting the next
conflictPattern	none	Regex over running processes' command lines; matches are shown as warnings
freshMarker	none	File written once every tracked output is newer than its sources
errorPattern, warnPattern	built in	Regexes that colour log lines and feed get_errors
urlPattern	Local:\s+(https?://\S+)	Picks the dev server's URL out of its output

Each process

Key	Default	Meaning
id	required	Letters, digits, -, _
kind	required	watch (a build watch) or serve (a dev server)
command	required	Run through the shell, as written
label	id	Display name
cwd	config folder	Working folder
env	{}	Extra environment variables
autostart	true	Start it at launch (--only overrides)
waitForReady	true for watch	Wait for its first build before starting the next process
preset	none	Readiness patterns: angular-library, angular-app, vite, tsc-watch, none
signals	from preset	{ "building": [...], "ready": [...], "error": [...] } regexes; replace the preset per state
port	none	If busy, wait and retry instead of crashing
buildOnce	none	One-off build command (enables "Build once" and stale rebuilds)
sources, output	none	Folders compared by modification time to detect a stale build
watchPaths	[sources]	After a crash loop, a save here restarts the process

A process with no ready signals counts as ready as soon as it starts.

---

Command line

devloop-supervisor [init | mcp] [options]

  --config <file>     config file (default: nearest devloop.config.json)
  --only <a,b>        start only these processes
  --port <n>          override the port
  --heap <mb>         override heapMb
  --skip-prepare      skip prepare and stale-output builds
  --detach            run in the background
  --open              open the status page
  --stop              stop the running supervisor
  --status            print its status

Options also accept key=value (only=web port=4300 detach=1), which suits Makefiles.

---

For coding agents (MCP)

The supervisor speaks the Model Context Protocol, in two ways:

stdio (works with any MCP client). The mcp command connects to the supervisor running for this project:

claude mcp add devloop -- npx devloop-supervisor mcp

Or in a client's JSON config:

{ "mcpServers": { "devloop": { "command": "npx", "args": ["devloop-supervisor", "mcp"] } } }

HTTP (no extra process), at http://127.0.0.1:4290/mcp:

claude mcp add --transport http devloop http://127.0.0.1:4290/mcp

Tools

Tool	What it does
get_status	Every process: state, last build result, restarts, dev server URL
get_errors	Recent error lines, from all processes or one
get_logs	Recent output of one process (optionally errors only)
wait_for_builds	Waits until nothing is building, then returns status and errors
restart_process	Restarts a process (also clears a crash-loop pause)
start_process / stop_process	Starts or stops a process
build_once	One-off build of a stopped watch

A typical agent loop: edit files → wait_for_builds → fix whatever get_errors reports → repeat.

---

Security

• The server listens on 127.0.0.1 only and refuses requests whose Host isn't 127.0.0.1 or localhost (blocks DNS rebinding).
• State-changing API calls need an X-Devloop header, which forces a CORS preflight that is never granted.
• /mcp accepts only application/json bodies and rejects non-local Origins.
• Commands come only from your config file; nothing received over HTTP or MCP is ever run as a command.

---

Development

npm test

The tests start a real supervisor over fake build and serve processes and drive it through the HTTP API, the HTTP MCP endpoint and the stdio MCP server.

License

MIT