Background agents with run_in_background: when it pays off

The first time I ran npx next build in a Claude Code session, the agent sat there for 90 seconds doing nothing while the build chugged. I sat there watching it. I could have been doing something else. The agent could have been doing something else. run_in_background exists exactly for that moment, and I had not noticed the flag.

This tutorial walks through when to use run_in_background on Claude Code's Bash tool, what you get, and the three commands I always background now.

Prerequisites

• Claude Code installed and running (CLI or the IDE extension).
• A project where you can run a dev server, a build, or a test suite. Any Next.js, Vite, or similar setup works fine.
• Familiarity with running bash commands inside Claude Code (the Bash tool).

No additional packages. run_in_background is a parameter on the existing Bash tool.

What run_in_background actually does

When you invoke the Bash tool normally, the call blocks until the command exits. Agent waits. You wait. The whole conversation waits.

When you invoke the Bash tool with run_in_background: true, the command starts, the tool returns immediately with a reference ID, and the command keeps running in the background. The agent can continue doing other work. When the command finishes, the harness notifies you, and the agent can check the output.

This is not parallel dispatch. Parallel dispatch spawns another sub-agent. Background Bash runs one command asynchronously inside the same agent. Different pattern, different use cases.

Step 1: identify what to background

Three categories of commands are almost always worth backgrounding.

Long builds and installs.

npm install
npx next build
cargo build --release

These take 30-180 seconds and the agent has nothing to do while they run. Background them.

Dev servers.

npx next dev
npm run dev
python manage.py runserver

A dev server never exits on its own. Backgrounding is mandatory, not optional. Foreground would hang the entire session.

Test runs.

npm test
pytest tests/
cargo test

Tests often take 30-120 seconds. The agent can start reading the next file or writing the next section while the test runs.

Step 2: use the run_in_background flag

In Claude Code, the Bash tool accepts the flag:

Bash(command: "npx next build", run_in_background: true)

The tool returns immediately with something like:

Started background task with ID bash-42.
Check output with BashOutput.

The agent now moves on. The build runs in the background. When the build finishes, the harness sends a notification into the conversation.

Step 3: check output later

When you want to see the result, use BashOutput (the companion tool):

BashOutput(bash_id: "bash-42")

This returns whatever the command has produced so far (stdout + stderr + exit code if finished). You can poll this repeatedly to watch a long-running command, though usually you just wait for the finish notification.

If the command is still running and you want to stop it, KillShell does that:

KillShell(bash_id: "bash-42")

Step 4: chain foreground work alongside background

Here is where the pattern pays off. With a build running in the background, the agent can do other work.

Step 1: Start build in background.
  Bash(command: "npx next build", run_in_background: true)
  → bash-42

Step 2: While build runs, read and update source.
  Read(file_path: "src/lib/content.ts")
  Edit(...)
  Edit(...)

Step 3: Check build output.
  BashOutput(bash_id: "bash-42")
  → compiled successfully or errors

Wall-clock time: roughly the longer of "do the other work" and "build." Without backgrounding, wall-clock would be "do the other work" + "build" serially.

Step 5: use it for a live dev server

The most practical use case in a DTC ecommerce workflow I do a lot: start a dev server, then do verification work against the running server.

Step 1: Start dev server in background.
  Bash(command: "npx next dev --port 4040", run_in_background: true)
  → bash-50

Step 2: Wait a few seconds for the server to come up.
  Bash(command: "sleep 5")

Step 3: Smoke test with curl.
  Bash(command: "curl -s http://localhost:4040/")
  → HTML response

Step 4: When done, kill the server.
  KillShell(bash_id: "bash-50")

Without backgrounding, step 1 would block forever because the dev server never exits. Backgrounding is the only way this shape works.

Common mistakes

Forgetting to kill background processes. Dev servers keep running after you are done with them. If you started a server on port 4040 and do not KillShell it, the port stays occupied. Next session starts another one on 4041. Clean up.

Backgrounding short commands. A 2-second ls does not benefit from backgrounding. The polling overhead eats the savings. Foreground anything under 10 seconds.

Trying to read stdout live. BashOutput gives you what has been emitted so far, but tailing a live output with tight loops eats tokens. If you want live feedback, run the command foreground and accept the wait.

Running interactive commands in the background. git rebase -i, npm publish, anything that prompts for input, these do not work in the background. They sit waiting for input that never comes. Keep interactive commands foreground, or use tmux for genuine interactivity.

Assuming the task notifies you. The harness does notify when background tasks complete, but do not count on the notification arriving at the exact moment you need it. If you need to synchronize, poll BashOutput or add an explicit wait step.

What to try next

Three patterns to layer on once run_in_background feels natural.

Parallel backgrounds. Start multiple long commands at once. Build, tests, and lint all in background. Check each one in turn.

Background + sub-agent. Dispatch a sub-agent while a build runs in background. The sub-agent returns a summary around the same time the build finishes. Two kinds of parallelism stacked. The parallel dispatch post covers the sub-agent side.

Background + worktrees. For serious multi-branch work, combine backgrounding with git worktrees so parallel builds run against isolated file states. Git worktrees for parallel agents is the full setup.

For operators building real pipelines, the Claude Code skills pack ships with skills that use backgrounding for the common builds and tests in a DTC ecommerce stack. The agent engineering handbook indexes the full set of concurrency patterns.

FAQ