agent-orchestrator/.claude/rules/56-electrobun-launch.md

Electrobun Launch Sequence (MANDATORY)

Use the agor-launcher MCP tools for ALL app lifecycle operations. Do NOT use raw bash commands for launch/stop/rebuild.

MCP Tools (preferred)

Tool	Use When
mcp__agor-launcher__agor-start	Launch the app (clean: true to rebuild from scratch)
mcp__agor-launcher__agor-stop	Stop all running instances
mcp__agor-launcher__agor-restart	Stop + start (clean: true for clean restart)
mcp__agor-launcher__agor-clean	Remove build caches without launching
mcp__agor-launcher__agor-rebuild	Full rebuild: npm install + vite build + native C lib + PTY daemon
mcp__agor-launcher__agor-status	Check running processes, ports, window
mcp__agor-launcher__agor-kill-stale	Kill accumulated stale agor-ptyd processes
mcp__agor-launcher__agor-build-native	Rebuild libagor-resize.so + agor-ptyd

Fallback (if MCP unavailable)

./scripts/launch.sh start          # normal launch
./scripts/launch.sh start --clean  # clean build + launch
./scripts/launch.sh stop           # stop all
./scripts/launch.sh rebuild        # full rebuild
./scripts/launch.sh status         # check state
./scripts/launch.sh kill-stale     # clean up stale ptyd

What Happens If You Skip Steps

• No PTY daemon: App crashes with Connection timeout (5s). Is agor-ptyd running?
• No Vite: WebView loads blank page (no frontend bundle)
• No kill first: Duplicate windows, port conflicts

Rules

• ALWAYS use agor-stop before agor-start when relaunching
• Use clean: true when src/bun/ files changed (Electrobun caches bundles)
• Use agor-rebuild after dependency changes or native code changes
• Use agor-kill-stale periodically (ptyd accumulates across sessions)
• NEVER launch manually with raw bash — always use MCP or scripts/launch.sh