process-monitoring

Process Monitoring Without Sleep

Never use sleep, for loops with delays, or while ! curl; do sleep polling patterns in the Cursor Shell tool. The Shell tool has built-in mechanisms for waiting.

Core Principle

The Shell tool's block_until_ms parameter IS the wait mechanism. Terminal output files ARE the monitoring mechanism. You never need to build your own waiting logic.

Pattern 1: Terminating Commands (build, seed, install, test)

Set block_until_ms higher than expected runtime. The shell blocks until the command finishes or the timeout is reached.

# Good: block for up to 120 seconds
Shell(command="pnpm db:seed", block_until_ms=120000)

# Bad: background then sleep-poll
Shell(command="pnpm db:seed &")
Shell(command="sleep 10 && check result")

If the command exceeds block_until_ms, it moves to background automatically. Check the terminal file for the exit_code footer.

Pattern 2: Long-Running Commands (dev server, watcher)

Use block_until_ms: 0 to immediately background, then read the terminal file to check for readiness markers.

# Step 1: Start in background
Shell(command="pnpm dev", block_until_ms=0)
# Returns terminal file path immediately

# Step 2: Read terminal file to check if ready
Read(path="/path/to/terminal/file.txt", offset=-20)
# Look for "ready in" or "Local: http://localhost:3000"

Readiness markers by tool:

Tool	Ready marker
Vite	ready in or Local: http://localhost:
Next.js	Ready in or started server on
Express/Fastify	listening on
Any build	exit_code: footer in terminal file

Pattern 3: Checking if a Background Command Finished

Read the terminal file. If finished, an exit_code footer appears:

---
exit_code: 0
elapsed_ms: 12345
ended_at: 2026-03-01T...
---

If still running, the header shows running_for_seconds (updated every 5s).

Pattern 4: Verifying a Running Server

Instead of curl polling, just read the terminal file output: