Background Tasks

What You’ll Learn

Some operations take time. Running a full test suite might take 30 seconds. Building a Docker image might take 2 minutes. Deploying to staging might take 5 minutes. Without background tasks, Claude Code would sit idle, burning context and your patience.

By the end of this session, you’ll understand:

• Why some tasks should run in the background
• The background task lifecycle: launch, monitor, notify
• How the notification queue reports completions
• When to use foreground vs. background execution
• How to keep doing useful work while waiting

The Problem

Consider this scenario:

User: "Run the full test suite, then fix any failing tests."

Without background tasks:
  AI: Runs test suite...
      ████████░░░░░░░░░░░░ 45%
      ... (you wait 90 seconds) ...
      ████████████████████ 100%
  AI: "3 tests failed. Let me fix them."

Those 90 seconds are wasted. The AI could have been reading the test files, analyzing likely failure patterns, or preparing fixes. Instead, it blocked on a synchronous call and did nothing.

This is the idle waiting problem. Synchronous execution means the AI can only do one thing at a time, even when the current operation doesn’t need its attention.

How It Works

Foreground vs. Background

Claude Code supports two execution modes:

Foreground (blocking):
  ┌──────────┐     ┌──────────┐     ┌──────────┐
  │  Start   │────►│  Wait... │────►│  Result  │
  │  command │     │  (idle)  │     │  ready   │
  └──────────┘     └──────────┘     └──────────┘
  Time: ============================|

Background (non-blocking):
  ┌──────────┐     ┌──────────────────────────────┐
  │  Start   │────►│  Continue working...          │
  │  command │     │  Write code, read files, plan │
  └──────────┘     │  ...                          │
                   │  ◄── Notification: "Done!"    │
                   └──────────────────────────────────┘
  Time: ====|  (productive work fills the gap)

The key difference: in background mode, the AI gets control back immediately and can do other work while the operation runs.

The Background Task Lifecycle

Every background task follows three phases:

┌─────────────────────────────────────────────────────┐
│              Background Task Lifecycle               │
│                                                      │
│  Phase 1: LAUNCH                                     │
│  ┌────────────────────────────────────────┐          │
│  │  Tool call with run_in_background=true │          │
│  │  → Process starts in daemon thread     │          │
│  │  → AI receives confirmation instantly  │          │
│  │  → AI continues with next action       │          │
│  └────────────────────────────────────────┘          │
│                                                      │
│  Phase 2: MONITOR                                    │
│  ┌────────────────────────────────────────┐          │
│  │  Background process runs independently │          │
│  │  → stdout/stderr captured              │          │
│  │  → Exit code tracked                   │          │
│  │  → No AI attention required            │          │
│  └────────────────────────────────────────┘          │
│                                                      │
│  Phase 3: NOTIFY                                     │
│  ┌────────────────────────────────────────┐          │
│  │  Process completes (success or failure) │          │
│  │  → Result placed in notification queue │          │
│  │  → AI receives notification in next    │          │
│  │    turn's context                      │          │
│  │  → AI can act on the result            │          │
│  └────────────────────────────────────────┘          │
│                                                      │
└─────────────────────────────────────────────────────┘

Launching a Background Task

The run_in_background parameter is available on the Bash tool:

{
  "type": "tool_use",
  "name": "Bash",
  "input": {
    "command": "npm test",
    "description": "Run full test suite",
    "run_in_background": true
  }
}

When this executes:

1. The test suite starts running in a separate process
2. The AI immediately receives a confirmation: “Background task started”
3. The AI’s next action can be anything — it doesn’t have to wait

Compare with a foreground call (the default):

{
  "type": "tool_use",
  "name": "Bash",
  "input": {
    "command": "npm test",
    "description": "Run full test suite"
  }
}

This blocks until npm test finishes. The AI cannot do anything else during execution.

The Notification Queue

When a background task completes, its result enters a notification queue. The AI sees it in a subsequent turn:

Turn N:
  AI launches background task: "npm test"
  AI continues: reads files, writes code...

Turn N+1:
  [System notification]
  Background task completed:
    Command: npm test
    Exit code: 1
    Output: "47 passed, 3 failed
      FAIL: src/auth/login.test.ts
      FAIL: src/auth/session.test.ts
      FAIL: src/api/users.test.ts"

  AI: "The test suite found 3 failures. Let me fix them."

The notification arrives naturally in the conversation flow. The AI doesn’t need to poll or check — it’s informed automatically when the background task finishes.

What Runs Well in Background

Not every command belongs in the background. Here’s a decision framework:

Need the result to decide your next action?
  ├── YES → Foreground (blocking)
  │   Examples:
  │   - "cat package.json" (need to read contents now)
  │   - "git status" (need to know state before committing)
  │   - "ls src/" (need to know what files exist)
  │
  └── NO → Background (non-blocking)
      Examples:
      - "npm test" (can write code while tests run)
      - "docker build ." (can prepare deployment config while building)
      - "pnpm build" (can write documentation while building)

Operation	Duration	Background?	Why
cat file.txt	< 1s	No	Result needed immediately
git diff	< 1s	No	Need to see changes now
npm test	10-120s	Yes	Can work while tests run
docker build	30-300s	Yes	Long build, result not needed immediately
npm install	5-30s	Maybe	Depends on whether you need the packages right away
pnpm build	5-60s	Yes	Can prepare deploy config in parallel
eslint .	5-30s	Yes	Can continue coding while linting

Interleaving Background and Foreground Work

The real power emerges when you combine background tasks with productive foreground work:

Timeline:
  ├── Launch: npm test (background)
  ├── Read: src/auth/login.ts (foreground, instant)
  ├── Read: src/auth/session.ts (foreground, instant)
  ├── Edit: fix suspected bug in login.ts (foreground)
  ├── [Notification: npm test completed, 3 failures]
  ├── Analyze: compare failures with the fix just made
  ├── Edit: fix remaining 2 test failures
  └── Launch: npm test (background, verify fixes)

The AI used the test suite’s execution time productively: it read the likely-broken files and started fixing the most obvious issue before the test results even came back.

Key Insight

Background tasks let you avoid idle waiting — the AI can do useful work while long operations run. This isn’t just an optimization; it fundamentally changes how the AI approaches complex tasks.

Without background execution, every long operation creates a dead zone in the conversation. The AI launches a build, waits 60 seconds doing nothing, then continues. Those 60 seconds could have been spent reading documentation, writing code, or planning next steps.

The insight goes deeper: background tasks change the AI’s planning strategy. When the AI knows it can run tests in the background, it’s more willing to launch tests early (to get fast feedback) rather than waiting until it thinks everything is perfect. This leads to a more iterative, feedback-driven workflow — closer to how experienced developers actually work.

Think of it like cooking. A good chef doesn’t stand in front of the oven watching the roast. They start the roast, then chop vegetables, prepare the sauce, and set the table. The oven notifies them when it’s done. Background tasks give the AI this same ability to interleave operations.

Hands-On Example

Running Tests While Writing Code

Here’s a realistic workflow that leverages background tasks:

User: "Fix the failing tests in the auth module"

AI Plan:
  1. Run test suite in background to identify failures
  2. While tests run, read the auth module source code
  3. When test results arrive, cross-reference with source
  4. Fix each failure
  5. Re-run tests in background to verify

Execution:

Step 1: Launch tests in background
  → Bash(command="npm test -- --reporter json", run_in_background=true)
  → "Background task started"

Step 2: Read source files (while tests run)
  → Read("src/auth/middleware.ts")
  → Read("src/auth/routes.ts")
  → Read("src/auth/session.ts")
  → (AI now understands the auth module's structure)

Step 3: Test results arrive
  → Notification: 3 tests failed
     - login.test.ts: "Expected 200, got 401"
     - session.test.ts: "Token expired error"
     - users.test.ts: "Missing required field"

Step 4: Fix with full context
  → AI already read the source files, can immediately
     correlate failures with code
  → Edit middleware.ts: fix token validation
  → Edit routes.ts: add missing field

Step 5: Verify in background
  → Bash(command="npm test", run_in_background=true)
  → Continue documenting the changes while tests run

Background Tasks with Timeouts

Long-running tasks can specify a timeout to prevent runaway processes:

{
  "type": "tool_use",
  "name": "Bash",
  "input": {
    "command": "npm run e2e-test",
    "description": "Run end-to-end test suite",
    "run_in_background": true,
    "timeout": 300000
  }
}

The timeout parameter (in milliseconds) ensures the background task doesn’t run indefinitely. If the process exceeds the timeout, it’s terminated and the AI receives a timeout notification.

Anti-Patterns to Avoid

Bad: Running a quick command in background
  → Bash(command="cat README.md", run_in_background=true)
  → Overhead of notification queue isn't worth it for <1s operations

Bad: Launching many background tasks that compete for resources
  → 5 parallel "npm test" runs will slow each other down
  → Better: one background test run + foreground analysis

Bad: Launching a background task then immediately waiting for it
  → Bash(command="npm test", run_in_background=true)
  → Bash(command="sleep 30")  ← defeats the purpose!
  → Instead: do useful work, let the notification come naturally

What Changed

Foreground Only	With Background Tasks
AI idles during long operations	AI works productively while waiting
One operation at a time	Interleaved foreground and background work
Tests run only when “ready”	Tests run early for fast feedback
Sequential workflow	Overlapping execution phases
90s test run = 90s of nothing	90s test run = 90s of productive coding
Build-then-deploy waits twice	Build in background, prepare deploy config simultaneously

Next Session

Session 9 introduces Agent Teams & Communication — how multiple Claude Code instances work together with independent context windows, communicating through a JSONL message bus to tackle problems too large for a single agent.