Background Agents and Async Work

Writing a test suite across thirty files. Refactoring an entire module. Investigating how a legacy codebase handles authentication. You know these jobs need doing. You also know that watching a progress bar for twenty minutes isn't productive.

Background agents let you hand off the work and keep building. Claude Code works on the task concurrently in its own context while you stay productive in your main session.

How Background Agents Work

Two modes. Foreground blocks your session until done. Background lets the agent work while you do something else entirely.

The key difference is permissions. Before a background agent starts, Claude Code asks you to approve tool permissions upfront. Makes sense: a background agent can't interrupt you mid-thought to ask "can I write to this file?" So it gets everything it might need approved in advance, and auto-denies anything that wasn't pre-approved.

If the agent hits a wall because it needed a permission you didn't grant, just resume it in foreground. It picks up exactly where it left off, now able to ask interactively. Nothing lost.

Launching Background Work

Several ways to kick off background work. The simplest: during a conversation, just specify that a subagent task should run in the background. Agent spins up, you get a confirmation, your session stays responsive.

But here's the one that really changes how you work. You started something in foreground, and five minutes in you realize it's going to take a while. Hit Ctrl+B. The task moves to the background and you get your session back instantly. Once you know about this, you'll use it constantly.

For tasks that should always be backgrounded, set background: true in the subagent configuration. Good for recurring patterns where you know the work is independent.

When a background agent finishes, notification hooks fire. You get a summary of what happened, what changed, and whether anything needs attention. If you need to disable background tasks entirely (some environments require it), set CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1.

Non-Interactive Mode and Fan-Out Patterns

Background agents are great inside Claude Code. But the async pattern goes further.

Non-interactive mode (claude -p) lets you run Claude Code from the command line without a session. Batch processing, CI/CD integration, and the fan-out pattern is where it gets genuinely powerful.

Twenty components that all need the same kind of update? Write a loop that calls claude -p for each one. Twenty parallel processes, each scoped to its own task, all running simultaneously. Use --allowedTools to lock down permissions tightly for batch operations. Each process gets only the tools it needs, which matters when you've got many agents running at once.

This pairs naturally with agent teams. A coordinator agent fans out work to multiple background agents, collects results, synthesizes them. Feels closer to managing a build pipeline than having a conversation.

Try It

Start a Claude Code session and give it two tasks. First, ask it to write comprehensive tests for one of your modules and send that to the background with Ctrl+B. Then, while that's running, start working on a completely different feature in your main session.

When the background agent finishes and notifies you, review the tests it wrote. Check if it needed any permissions it didn't have. If it got stuck somewhere, resume it in foreground to grant what it needs and let it finish.

For a more advanced exercise, pick five files that need similar refactoring (maybe updating imports, renaming a function, or adding error handling). Write a shell script that loops through the files and calls claude -p "Refactor the error handling in [file] to use the new AppError class. Only modify [file]." --allowedTools "Edit,Read" for each one. Watch all five run in parallel and compare the results.

Background vs. Foreground

Dead simple decision. If the work is independent and you don't need results to keep going, background it. If you need the output for your next step, foreground.

Good background candidates: writing tests, generating docs, refactoring isolated modules, researching patterns in a large codebase. Anything where the agent can work alone and you review later.

Keep things foreground when you're exploring together, when the output determines your next move, or when the task needs frequent judgment calls. Interactive problem-solving doesn't benefit from being backgrounded.

Quick litmus test: if you'd be comfortable delegating this to a colleague and checking their work tomorrow morning, background it. If you'd want to pair on it, foreground.

The Shift

Background agents match AI workflows to how we actually work. Juggling multiple streams, context-switching when blocked, reviewing completed work in batches. Nobody sits watching one process run to completion.

Each background agent gets its own context window, its own working memory. It can't see your main session. You can't see its intermediate reasoning. That's a feature, not a limitation. It forces clean task boundaries.

As you get comfortable with this, your thinking changes. Instead of "how do I build this step by step," you start asking "which parts of this can happen in parallel." That reframing matters more than any individual tool feature.