If you've heard people talk about Claude Code background agents, you may wonder what they actually are and how they differ from Claude Code subagents, agent teams, or simple background shell commands.
The terminology can be confusing because “background agents” is commonly used by the community, while Anthropic's current documentation describes the underlying feature as background sessions managed through Agent View.
A background session is essentially a full Claude Code conversation that continues running without staying attached to your terminal. You can hand Claude a task, let it work independently, and continue with something else. Later, you can check its progress, answer questions, attach to the session, or review the result.
This makes background sessions useful for developers who want Claude Code to handle independent coding, testing, research, debugging, or review tasks while they continue working elsewhere.
Anthropic currently describes Agent View as a research-preview feature for dispatching and monitoring multiple background sessions.
What Are Claude Code Background Agents?
A Claude Code background agent is commonly used to describe a Claude Code session that runs in the background without an attached terminal.
The more precise Anthropic terminology is:
- Background session — the full Claude Code conversation running separately from your active terminal.
- Agent View — the interface used to dispatch, monitor, peek into, and attach to background sessions.
- Background agents — the informal term commonly used when referring to this workflow.
You can open Agent View with:
claude agents
From there, you can dispatch multiple independent tasks. Each prompt you submit creates its own background session. You can then monitor those sessions from one screen instead of opening a separate terminal for every task.
For example, you could have:
- Agent 1 investigating a failing authentication test
- Agent 2 reviewing an API implementation
- Agent 3 updating documentation
- Agent 4 investigating a performance problem
Meanwhile, you continue working on your main feature.
Why Background Agents Matter
Normal Claude Code usage is interactive: you give Claude a task, watch it work, review the output, and then move on to your next task.
Background sessions change that workflow.
Instead of:
Task → Wait → Review → Next task
you can do:
Task A → Background
Task B → Background
Task C → Background
Then monitor all three and step in only when one needs your attention.
Anthropic's documentation specifically positions Agent View for independent tasks that can be handed off while you continue working elsewhere.
This is especially useful for:
- Long-running investigations
- Large codebase analysis
- Test generation
- Bug investigations
- Documentation work
- Code reviews
- Independent feature development
- API or framework research
- Security analysis
- Performance investigations
The key is that the tasks should be reasonably independent. If Task B depends directly on unfinished work from Task A, simply running both at the same time may create unnecessary coordination problems.
How Claude Code Background Sessions Work
Background sessions are not simply another terminal tab.
Claude Code uses a separate background service/supervisor to keep background sessions running independently of the terminal that started them. This is why closing the shell or Agent View does not automatically terminate the session.
Anthropic's current documentation explains that background sessions:
- Run without an attached terminal
- Continue while Agent View is closed
- Continue when the shell is closed
- Survive machine sleep
- Stop when the machine shuts down
- Can be reopened or resumed
- Can be monitored from Agent View
The supervisor architecture is important because it separates the lifecycle of the background session from your interactive terminal. A recent technical examination of the feature also describes the supervisor as the process that owns these sessions independently of the shell that launched them.
Sleep vs Shutdown
There is an important distinction:
Sleep: Background sessions can survive sleep and resume when the machine wakes.
Shutdown: A complete shutdown stops running local background sessions.
This means Claude Code's local background agents are not equivalent to cloud-based autonomous agents that continue working while your computer is completely offline.
If you need work to continue while your machine is powered off, Claude Code's cloud-based options are a different category.
Three Ways to Start a Background Session
There are several ways to start background work in current Claude Code.
1. Start from Agent View
Run:
claude agents
Agent View gives you a central interface where you can enter a task.
For example:
Investigate why the checkout integration tests are flaky. Identify the likely cause, reproduce the issue if possible, and prepare a fix.
Press Enter and Claude creates a background session.
You can then dispatch another task:
Review the authentication middleware for security issues.
That creates another session rather than sending a follow-up to the first one.
2. Background an Existing Session
If Claude is already working on a task and you decide you don't want to wait, you can move the current session into the background.
Use:
/bg
or:
/background
Current Claude Code documentation also supports using the left-arrow workflow from an empty prompt to move a session into Agent View.
The important point is that backgrounding doesn't mean stopping. The session continues running after you detach from it.
3. Start Directly from the Shell
You can also dispatch a background session directly:
claude --bg "investigate the flaky checkout test"
You can also specify options such as the model when launching a session:
claude --bg --model opus "review the authentication implementation"
This approach is useful when you already know that the task should run independently from the beginning. Current Claude Code documentation lists claude --bg as one of the supported ways to start background sessions.
How to Monitor Background Agents
Once you have several sessions running, the main question becomes:
How do I know what Claude is doing?
That's where Agent View becomes useful.
Run:
claude agents
You can see sessions grouped by states such as:
- Needs input
- Working
- Ready for review
- Completed
A session may need your attention because Claude is asking a question, waiting for permission, or needs information that only you can provide.
Peek Without Opening the Full Session
You don't always need to attach to a session.
In Agent View, select a session and press:
Space
This opens a peek panel showing the latest status or the question Claude is waiting on.
You can reply directly from the peek panel.
This is useful because you can manage several agents without constantly jumping between full conversations.
Attach to a Session
When you need more control, attach to the session.
In Agent View, select the session and press:
Enter
or:
→
You then enter the full Claude Code conversation.
When finished, you can detach again without stopping the session.
Background Sessions and Git Worktrees
One of the most important parts of background-agent architecture is file isolation.
When a background session is working inside a Git repository, Claude Code normally moves it into its own isolated Git worktree before editing files.
That means multiple background sessions can work against the same repository without automatically editing the same checkout.
For example:
Main repository
├── Background Session A
│ └── Worktree A
│
├── Background Session B
│ └── Worktree B
│
└── Background Session C
└── Worktree C
This is a major reason parallel background work is practical.
Agent A can investigate a bug while Agent B works on documentation and Agent C prepares a separate change.
However, isolation doesn't eliminate the need for good task planning. If two agents need to modify the same logical feature or depend on each other's unfinished work, you still need to coordinate them.
Claude Code's current documentation states that each background session normally gets an isolated worktree before editing files, while also documenting exceptions such as non-Git directories or explicitly disabled isolation.
Be Careful Before Deleting a Session
Worktree isolation protects parallel development, but there is an important cleanup issue.
If a background session has made changes inside a Claude-created worktree, deleting the session can also remove that worktree.
So before deleting a session, make sure the work you care about has been preserved.
Useful outcomes include:
- A commit
- A pushed branch
- A pull request
- Another saved copy of the work
Current Claude Code documentation explains that Agent View can remove Claude-created worktrees when a session is deleted, although there are additional safeguards for commits and unpushed changes.
A good habit is:
Don't treat a completed background session as disposable until you've checked where its code changes ended up.
Background Agents vs Background Commands
This is another common source of confusion.
A background agent/session is a Claude Code agent performing a multi-step task.
A background Bash command is simply a shell command running without blocking your main conversation.
For example:
npm install
or:
docker build .
can be long-running commands.
That doesn't make them agents.
The distinction is:
| Feature | Background Agent | Background Command |
|---|---|---|
| Runs | Claude Code session | Shell command |
| Reasoning | Yes | No agent reasoning |
| Handles multi-step task | Yes | No |
| Example | Investigate and fix a bug | npm install |
| Management | Agent View/session controls | Task/process controls |
| Best for | Coding, research, debugging | Servers, builds, logs, scripts |
ClaudeLog also distinguishes full background agents from background shell commands, describing agents as appropriate for complex multi-step tasks while background commands are better suited to processes such as development servers and logs.
Background Agents vs Subagents
This is probably the most important distinction to understand.
Subagents
A subagent works inside another Claude Code session.
It gets its own context and performs a delegated task, then reports the result back to the session that created it.
For example:
Main Claude session
↓
Subagent
↓
Research authentication
↓
Summary returned
↓
Main session continues
Subagents are particularly useful when you want to keep large amounts of research, logs, or file exploration out of your main conversation context.
Background Sessions
A background session is a separate full Claude Code conversation that you dispatch and monitor yourself through Agent View.
The simplest distinction is:
Subagent = worker inside a session
Background session = separate session you hand off and monitor
Anthropic's current parallel-work documentation makes this distinction explicit.
Background Agents vs Agent Teams
Agent teams are different again.
With Agent View, you dispatch and monitor independent sessions.
With agent teams, Claude can act as a lead that coordinates multiple sessions, with shared task tracking and inter-agent messaging.
Current Anthropic documentation describes agent teams as experimental and disabled by default.
Think about the difference this way:
Background sessions:
You
├── Agent A
├── Agent B
└── Agent C
Agent team:
Claude Lead
/ | \
Agent A Agent B Agent C
Background sessions are therefore a better mental model when you want to delegate independent work yourself.
Agent teams are designed for situations where the agents themselves need more coordination.
Background Agents vs Cloud Sessions
There is another important distinction.
Claude Code's local background sessions run on your machine.
Cloud sessions/projects are designed for work that can continue independently of your local machine.
Anthropic's current documentation describes Projects as a way to coordinate parallel cloud sessions for work spanning days or weeks and for situations where the work should continue when your machine is off.
So:
| Approach | Runs Where | Best For |
|---|---|---|
| Interactive Claude Code | Your machine | Direct coding |
| Background sessions | Your machine | Independent parallel tasks |
| Subagents | Inside a Claude session | Side tasks and context isolation |
| Agent teams | Local coordinated sessions | Multi-part projects |
| Cloud projects/sessions | Cloud | Long-running work beyond your machine |
This distinction matters because local background agents are not truly “always-on” cloud agents.
Best Use Cases for Background Agents
Background sessions work particularly well when the task is independent and can produce a useful result without constant supervision.
1. Bug Investigation
For example:
Investigate why the checkout test fails intermittently. Find the likely cause and propose a fix.
Start it in the background while you continue implementing another feature.
2. Code Review
You could ask one background session to review a completed feature:
Review the authentication changes for security issues, edge cases, and missing tests.
3. Large Codebase Research
Background sessions can investigate a large repository while you work on another part of the project.
4. Documentation
You can delegate documentation updates while continuing development.
5. Testing
One session can investigate failing tests while another session works on implementation.
6. Independent Feature Work
If two features touch different areas of the codebase, they may be suitable for separate background sessions.
7. API and Framework Research
You can delegate research into an unfamiliar API or library while preparing the implementation yourself.
Community documentation and practical guides also identify research, code analysis, documentation, security audits, and performance analysis as useful background-agent workloads.
When You Should NOT Use Background Agents
Background execution isn't automatically better.
Keep a task in the foreground when:
- You need to make frequent decisions
- The task requires constant clarification
- The next step depends on your immediate feedback
- Multiple tasks need to edit the same files
- The work has strict sequential dependencies
- You need to inspect every change as it happens
Parallelism can actually make a project harder to manage when tasks are tightly coupled.
For example, don't blindly create three agents if:
Agent A → must finish first
↓
Agent B → depends on A
↓
Agent C → depends on B
Running them simultaneously doesn't make the workflow faster.
Background agents are most useful when the tasks can genuinely be separated.
Background Agents and Context Windows
Another advantage is context separation.
A long research task can consume a large amount of context in your main Claude Code conversation.
A separate session keeps that work away from your main conversation.
Subagents take this even further by giving delegated work its own context window and returning a summary to the parent conversation. Anthropic specifically describes context preservation as one of the major reasons to use subagents.
This makes agent architecture closely connected to context engineering.
Instead of putting every file, log, search result, and investigation into one giant conversation, you can divide work into smaller contexts.
Background Agents Use Your Usage Quota
Parallel execution isn't free.
Each background session consumes your Claude subscription usage independently. Anthropic's current documentation warns that running ten sessions in parallel can consume quota roughly ten times as quickly as running one session, depending on the work being performed.
So don't create ten agents just because you can.
A better workflow is:
- Identify genuinely independent tasks.
- Dispatch only the useful ones.
- Give each task a precise objective.
- Monitor their progress.
- Review the resulting code or pull requests.
- Stop unnecessary sessions.
Parallelism should reduce waiting—not simply multiply token consumption.
A Practical Background-Agent Workflow
Here's a simple workflow you can use:
Step 1: Identify independent tasks
Suppose you're building a web application.
You have:
Task A: Fix authentication bug Task B: Review API error handling Task C: Update documentation Task D: Investigate slow test
These can potentially be handled independently.
Step 2: Open Agent View
claude agents
Step 3: Dispatch the tasks
Give each session a clear prompt.
For example:
Investigate the authentication bug in src/auth. Reproduce it, identify the root cause, and prepare a fix.
Then dispatch another:
Review the API error handling and identify missing validation, error responses, and tests.
Step 4: Continue your main work
Don't sit and watch every agent.
Work on your main feature while the background sessions run.
Step 5: Check Agent View
Return to:
claude agents
Look for sessions that are:
- Working
- Waiting for input
- Ready for review
- Completed
- Failed
Step 6: Peek first
Use the peek view to understand what happened without opening the entire conversation.
Step 7: Attach when necessary
If an agent needs detailed discussion, attach to its session and continue from there.
Step 8: Review the actual result
Don't assume that “completed” means “correct.”
Review:
- Code changes
- Tests
- Git branch
- Commit
- Pull request
- Error messages
- Uncommitted changes
Background execution changes who waits, not who is responsible for reviewing the result.
Current Limitations
Agent View is still a research preview, so behavior and interface details can change as Claude Code evolves.
The main limitations to understand are:
Local execution
Background sessions run on your machine.
Shutdown stops sessions
Sleep is supported, but shutting down the machine stops running sessions.
Usage is multiplied
Several concurrent sessions consume usage independently.
Parallel work still requires planning
Worktree isolation helps prevent direct file collisions, but agents can still have logical dependencies.
Worktrees need cleanup
If Claude created a worktree, understand what will happen to its changes before deleting the session.
Frequently Asked Questions
Is “Claude Code background agents” an official term?
Not exactly.
Anthropic's current documentation primarily uses background sessions and Agent View. “Background agents” is a commonly used community/search term for this functionality.
What command opens Agent View?
Use:
claude agents
It provides a dashboard for dispatching and monitoring background sessions.
Can I move an existing Claude Code session into the background?
Yes.
You can use:
/bg
or:
/background
You can also use the current Agent View keyboard workflow to background a session.
Can I start a background session directly from the shell?
Yes:
claude --bg "investigate the flaky checkout test"
Do background agents keep working when I close the terminal?
Yes. The background session is managed separately from the terminal and can continue after the shell or Agent View is closed.
Do they keep working after I shut down my computer?
No. Local background sessions stop when the machine shuts down. They can survive sleep.
Can multiple background sessions work on the same repository?
Yes. Claude Code normally isolates background sessions in separate Git worktrees before they edit files, which allows multiple sessions to work against the same repository without directly sharing the same checkout.
Do background agents use more Claude usage?
Yes. Each background session uses your subscription quota independently, so running multiple sessions increases usage accordingly.
Are background agents the same as subagents?
No.
A subagent runs inside a parent Claude Code session and returns results to that session. A background session is a separate full Claude Code conversation that you dispatch and monitor independently.
Are background agents the same as background Bash commands?
No.
A background Bash command runs a shell process without blocking your conversation. A background Claude session is a full agent capable of reasoning through a multi-step task.
Final Takeaway
Claude Code background agents are best understood as full Claude Code sessions that you can hand off and monitor while you continue working.
The current official terminology is background sessions, managed through Agent View.
The workflow is simple:
Give Claude a task
↓
Send it to the background
↓
Continue your own work
↓
Monitor with Agent View
↓
Peek or reply when needed
↓
Attach when you need control
↓
Review the final result
The biggest advantage isn't simply that Claude can “code by itself.”
It's that you can change your development workflow from waiting for one task to finish to delegating several independent tasks and reviewing them as they become ready.
For developers working on larger projects, this makes Claude Code feel less like a single interactive coding assistant and more like a system for managing multiple AI coding workers.
But the key is knowing which tool to use.
Use background sessions when you want to hand off independent work.
Use subagents when a side task belongs inside your current conversation.
Use agent teams when multiple sessions need coordinated work.
Use cloud sessions/projects when the work needs to continue independently of your local machine.
And always review the code before treating an agent's task as finished.