Start a dev server from Claude Code the naive way and the session locks up until you kill it. The agent ran a command, the command didn't exit, and now the tool call that started it is still "in progress" — no further edits, no more tool calls, nothing, until you Ctrl+C in a different terminal. Multiply that by builds, log tails, and test watchers and you get a workflow that's constantly blocked on processes that were never supposed to finish quickly in the first place.
Claude Code's background task support fixes this directly: long-running commands get launched, handed a task ID, and left running while the agent keeps working. This guide covers how run_in_background, output polling, and task termination fit together, and where background tasks are the wrong tool.
The Problem: Foreground Commands Block the Loop
Claude Code's Bash tool is synchronous by default — it runs a command, waits for it to exit, and returns the output. That's correct for the overwhelming majority of commands: npm install, git status, a one-shot test run. Each of those has a natural end.
Dev servers, log tails, and watch-mode processes don't have a natural end. npm run dev, tail -f, a file watcher — these are meant to keep running. Launched synchronously, the agent's tool call never returns, and the entire session stalls waiting on a process that was designed to run indefinitely. The workaround before background tasks existed was ugly: background the process with a trailing & and hope the shell state survived between tool calls, or ask the human to start the server in a separate terminal so the agent never had to touch it.
How Background Tasks Work
A command run with the background flag set doesn't block. Claude Code starts the process, immediately returns control to the agent, and tracks the running process under a task ID. The agent can keep calling other tools — reading files, making edits, running quick synchronous checks — while the backgrounded process keeps running in parallel.
Three pieces make this useful instead of just non-blocking:
- Launch. The agent starts a command with background execution enabled instead of the default synchronous mode, and gets a task identifier back instead of waiting for exit output.
- Read output on demand. A dedicated output tool lets the agent check accumulated stdout/stderr for a specific task at any point — after making a related change, before deciding whether a server restart succeeded, or when it wants to confirm a build actually finished.
- Stop it. A task-stop tool terminates a specific backgrounded process by ID, so the agent (or you) can kill a stuck dev server or a watcher that's no longer needed without hunting for the PID manually.
// Launch (conceptual — actual invocation is a Bash call with a background flag)
{ "command": "npm run dev", "run_in_background": true }
// Returns a task ID immediately, server keeps running
// Check output later
{ "task_id": "abc123" }
// Returns accumulated stdout/stderr since last check
// Stop it when done
{ "task_id": "abc123" }
// Terminates the processWhere This Actually Helps
The clearest case is iterative frontend work: start the dev server once in the background, then make edits and check the output tool for compile errors or hot-reload confirmations without ever re-running the server or losing its state. The agent isn't guessing whether a change worked — it's reading the same terminal output you'd be watching yourself.
The second case is long builds. A production build that takes several minutes doesn't need to freeze the whole session — background it, keep working on something independent (docs, a different file, a test), and poll the output when the build should be done rather than staring at a blocked tool call the entire time.
The third is log tailing during debugging: background a tail -f on a server log, reproduce the issue with a separate action, then read the accumulated output to see what the server logged during the reproduction — without the tail process itself ever needing to exit.
Where Background Tasks Are the Wrong Call
Not every slow command belongs in the background. If the very next thing the agent needs to do depends directly on that command's result — a migration that must finish before the next step touches the database, a test suite whose pass/fail gates whether to proceed — running it synchronously is correct even if it's slow. Background tasks solve the case where the agent has other useful work to do while a process runs, not the case where it's just waiting.
Overuse also creates its own mess: half a dozen abandoned background dev servers from earlier in a long session, each still holding a port, is a common failure mode. Stop tasks explicitly once you're done with them instead of letting them accumulate — a stale server on port 3000 that nobody remembers starting is exactly the kind of drift that turns into "why is this port already in use" ten minutes later.
How This Fits With the Rest of the Toolchain
Background tasks solve a narrower problem than scheduled cron jobs, which run a command on a recurring interval independent of the current session. A background task is scoped to the session it was launched in — it runs alongside the current work, not on a schedule after the session ends. If you need something to run every five minutes indefinitely, that's a cron job; if you need a dev server alive for the next twenty minutes while you iterate, that's a background task.
They also pair naturally with permission modes: an agent running with more autonomy can start and manage its own dev servers without stopping to ask each time, while a more conservative permission setup can still require confirmation before launching a long-lived background process.
The Takeaway
Background tasks close a real gap: commands that are supposed to keep running no longer force the whole agent loop to keep waiting. Launch with a background flag, check output when you actually need to know what happened, and stop tasks explicitly instead of letting them pile up. The judgment call that matters is the same one that applies everywhere else in Claude Code — background what genuinely runs in parallel with your next steps, and run synchronously anything the next step actually depends on.