Background tasks and monitoring

Background tasks

When Claude proposes a Bash command, it can pass run_in_background: true. The command starts, control returns to the conversation immediately, and Claude keeps working. The command’s output is written to a log file. When the command exits — success or failure — you get one notification.

The right use cases:

• A build. “npm run build” takes 90 seconds. Fire it in the background; keep going.
• A dev server. Starts once, runs indefinitely, you want to know if it dies.
• A long test suite. Same idea.

You do not want a background task when the very next step depends on the output. Fire-and-forget is the model.

Monitors

A monitor is a longer-lived Bash process whose every stdout line becomes a notification. Instead of “tell me when it exits”, it is “tell me every time something interesting happens”.

Common shapes:

• tail -f server.log | grep --line-buffered ERROR — alert on every error line.
• A poll loop that emits a line every time a CI check completes.
• inotifywait -m on a directory that emits a line every time a file changes.

The rule of thumb: background for “notify me once when done.” Monitor for “notify me each time X happens.”

Notifications

Notifications come back into the conversation as system messages. You do not have to actively check anything. The conversation stays interactive; you keep working; when a background task finishes or a monitor line fires, it shows up.

When to reach for background

• Anything that would block a prompt for more than a few seconds where you have other work to do.
• Long dev servers and processes you want up for the whole session.
• Compilations and builds that will complete on their own.

When to reach for monitor

• Log files where certain lines are actionable.
• CI pipelines where each check landing matters.
• File-system events you want to react to.

Reading the log

Both background tasks and monitors write output to a log file whose path Claude Code will tell you. You can Read that file at any time to see the full output — Claude does not summarise it away unless you ask.

Check your understanding

Quick check

—

You want to be notified every time an ERROR line appears in a running dev server's log, so you can react while continuing other work. Which primitive fits best?

1. AA background task — start the dev server with run_in_background and check the log manually every few minutes.
2. BA monitor watching `tail -f dev.log | grep --line-buffered ERROR` — each matching line becomes a notification in the conversation.
3. CA subagent that keeps re-reading the log.
4. DNothing — just refresh the browser.

Check answer→