Background Process Best Practices

Keep the Process List Clean

• Kill processes when done - don't leave stale servers running
• Use background_process_cleanup periodically to remove exited processes
• Before launching, check background_process_list to avoid duplicates
• Use remove: true when killing to clean up in one step

Verify Startup

After launching, wait before reading output - servers need time to start:

1. Launch the process
2. Sleep at least 30 seconds (use bash sleep or just wait before next action)
3. background_process_read to confirm startup
4. If output is empty or incomplete, wait longer and re-read

Look for: "listening on", "ready", "started" - or errors like port conflicts

Use Meaningful IDs

When running multiple processes, set custom id for clarity:

• id: "frontend" and id: "backend" instead of vite-1, node-2
• Makes kill/read commands unambiguous

When to Use Each Signal

• Processes persist for the session - they don't auto-cleanup on conversation end
• Output buffer is limited (500 lines default) - increase maxOutputLines for verbose builds
• stderr is prefixed with [stderr] in output - helps distinguish errors