Background Tasks - Claude Code

Background tasks let long-running shell commands run alongside your session without blocking the prompt.

What it does

Press Ctrl+B or pass the background flag to a Bash tool call, and Claude starts the command asynchronously. You get a task ID back immediately. Claude can poll the task's stdout and stderr later, stream new output into context, or stop it via TaskStop. This is how dev servers, test watchers, and long builds stay alive across turns.

When to use it

• Running npm run dev, pnpm test --watch, or similar long processes.
• Kicking off a build while Claude keeps coding.
• Tailing logs or monitoring a process without blocking your chat.
• CI-style jobs where you want Claude to check back periodically.

Gotchas

• Background tasks don't persist across sessions. Restart claims a fresh process.
• Output buffers have limits - very chatty processes may get truncated. Pipe to a file for full logs.
• Forgetting to stop a background task leaves orphaned processes. Always call TaskStop or close the session cleanly.

Official docs: https://code.claude.com/docs/en/interactive-mode.md#background-bash-commands