Skip to main content
The Bash tool supports running commands in the background, allowing you to start servers, watchers, or long-running tasks without blocking the chat.

​
Running Background Processes

// Start a process in background
Bash({ command: "npm run dev", background: true })
// Returns PID immediately: { pid: 12345 }

// Wait for the process to finish
Bash({ wait_pid: 12345 })
// Returns the full output when complete

​
In-Chat Commands

/bg                  List background processes
/bg kill <pid>       Kill a process
/bg logs <pid>       View process output

​
Use Cases

  • Dev servers: Start npm run dev or bun run dev for live preview
  • File watchers: Run nodemon or similar for auto-restart
  • Build processes: Long compilations that would timeout
  • Databases: Start local database servers

​
Best Practices

  1. Use background: true for processes that run indefinitely
  2. Don’t background one-shot commands (build, install, etc.) - use longer timeout instead
  3. Check logs with /bg logs <pid> to debug issues
  4. Kill processes with /bg kill <pid> when no longer needed