chore: Restore mprocs as default dev runner (#1303)

Author: charlesvien

CLAUDE.md

@@ -14,7 +14,8 @@
 ## Commands
 
 - `pnpm install` - Install all dependencies
-- `pnpm dev` - Run both agent (watch) and code app via phrocs
+- `pnpm dev` - Run both agent (watch) and code app via mprocs
+- `pnpm dev:ph` - Run both agent (watch) and code app via phrocs
 - `pnpm dev:agent` - Run agent package in watch mode only
 - `pnpm dev:code` - Run code desktop app only
 - `pnpm build` - Build all packages (turbo)

README.md

@@ -28,11 +28,12 @@ pnpm install
 # Copy environment config
 cp .env.example .env
 
-# phrocs is auto-installed on first `pnpm dev`
 ```
 
 ### Running in Development
 
+By default, `pnpm dev` uses [mprocs](https://github.com/pvolok/mprocs) to run the agent and code app in parallel.
+
 ```bash
 # Run both agent (watch mode) and code app in parallel
 pnpm dev
@@ -42,6 +43,20 @@ pnpm dev:agent  # Run agent in watch mode
 pnpm dev:code   # Run code app
 ```
 
+### phrocs (alpha)
+
+phrocs is our custom process runner built as a replacement for mprocs. It's currently in alpha and can be used as an alternative dev runner. phrocs does not auto-update — you must manually run the update command to pull the latest version.
+
+```bash
+# Run dev with phrocs (auto-installs on first run)
+pnpm dev:ph
+
+# Manually update phrocs to the latest version
+pnpm update:phrocs
+```
+
+phrocs reads the same `mprocs.yaml` config file. The binary is downloaded to `bin/phrocs` and is git-ignored.
+
 > **Want to connect to a local PostHog instance?** See [docs/LOCAL-DEVELOPMENT.md](./docs/LOCAL-DEVELOPMENT.md) for OAuth setup and connecting to localhost:8010.
 
 ### Utility Scripts

package.json

@@ -10,7 +10,8 @@
   "scripts": {
     "setup": "bash apps/code/bin/setup",
     "prepare": "husky",
-    "dev": "pnpm build:deps && bash scripts/ensure-phrocs.sh && bin/phrocs --config mprocs.yaml",
+    "dev": "pnpm build:deps && mprocs",
+    "dev:ph": "pnpm build:deps && bash scripts/ensure-phrocs.sh && bin/phrocs --config mprocs.yaml",
     "dev:agent": "pnpm --filter agent dev",
     "dev:git": "pnpm --filter @posthog/git dev",
     "dev:code": "pnpm --filter code start",
@@ -27,7 +28,8 @@
     "format": "biome format --write",
     "clean": "pnpm -r clean",
     "knip": "knip",
-    "skills:pull": "node scripts/pull-skills.mjs"
+    "skills:pull": "node scripts/pull-skills.mjs",
+    "update:phrocs": "rm -f bin/phrocs && bash scripts/ensure-phrocs.sh"
   },
   "keywords": [
     "posthog",
@@ -45,6 +47,7 @@
     "husky": "^9.1.7",
     "knip": "^5.66.3",
     "lint-staged": "^15.5.2",
+    "mprocs": "^0.7.1",
     "turbo": "^2.6.2"
   },
   "lint-staged": {