How to Use Claude Code's /bg Command to Run Background Agent Sessions

What the /bg Command Actually Does in Claude Code

Most developers who use Claude Code discover the /bg command by accident — they’re deep into a long-running task and realize they need to start something else without losing their current context. That’s exactly the problem /bg solves.

The /bg command in Claude Code moves your active session into what Anthropic calls Agent View, a background processing mode that lets the agent keep working while you open a new session, switch between tasks, or just step away. It’s one of the more underused features in Claude Code, largely because the documentation around it is sparse and most users are still working in single-session mode.

This guide explains how the /bg command works, when to use it, how to manage multiple background sessions effectively, and what to watch out for when you start running parallel agents across projects.

---

How Claude Code’s Agent View Works

Before getting into the command itself, it helps to understand the underlying model. Claude Code is built to function as an autonomous coding agent — it can read files, run commands, write code, and reason across multiple steps without you holding its hand at each stage.

Agent View is the interface layer that lets you run multiple of these agents simultaneously. Think of it like having several terminal sessions open at once, except each one has a Claude agent doing real work inside it.

When you issue the /bg command, Claude Code:

1. Detaches the current session from your active terminal view
2. Continues executing whatever task is in progress
3. Adds the session to a list of background agents you can monitor and switch to
4. Frees up your terminal for a new session

The agent doesn’t pause. It keeps running in the background — reading files, making edits, running tests — while you do other things.

---

Setting Up Claude Code for Background Sessions

Prerequisites

Before you can use /bg effectively, you need a working Claude Code setup. If you’re starting fresh:

• Install Claude Code via npm: npm install -g @anthropic-ai/claude-code
• Authenticate with your Anthropic API key
• Make sure you’re running Claude Code version 1.x or later (earlier versions had limited background session support)

You don’t need any special configuration to use background sessions — they’re available by default once Claude Code is installed.

Understanding the Terminal Environment

Claude Code runs inside your terminal, which means background sessions are tied to that terminal process. If you close the terminal, your background sessions end. For long-running tasks, this matters.

A few options to keep sessions alive across terminal closings:

• Use a terminal multiplexer like tmux or screen
• Run Claude Code inside a persistent shell session on a remote machine
• Use Claude Code’s built-in session persistence features if your version supports them

For most development work, running inside tmux is the most practical approach. You can detach from a tmux session and reconnect later without losing your Claude Code background agents.

---

Using the /bg Command Step by Step

Starting a Task and Moving It to the Background

Here’s the basic workflow:

1. Open Claude Code in your terminal
2. Navigate to your project directory
3. Give Claude Code a task — for example: “Refactor the authentication module to use JWT tokens and add proper error handling throughout”
4. Once the agent starts working, type /bg and press Enter

The session moves into the background immediately. Claude Code will confirm this with a message showing the session ID and a brief summary of what it’s doing.

You’ll then see a prompt to either start a new session or view your list of active background agents.

Viewing Your Background Sessions

To see all running background sessions, use:

/sessions

This lists all active agents with:

• Session ID
• Project directory
• Current task summary
• Status (running, waiting for input, completed, or error)
• How long the session has been running

Switching Between Sessions

To switch back to a background session:

/switch <session-id>

Or use the shorter form with just the first few characters of the session ID. Claude Code will bring that session back to the foreground, showing you the current state and any output it’s generated since you last checked.

Ending a Background Session

When a session is done, Claude Code will typically notify you (depending on your notification settings). You can also check in manually and close a completed session with:

/end <session-id>

Or just switch to it and type /exit to close it normally.

---

Running Parallel Agents Across Multiple Projects

The real value of /bg shows up when you’re working across multiple codebases at the same time. Here’s a practical example of how this looks in practice.

A Realistic Parallel Workflow

Say you’re working on a monorepo with a backend API and a frontend application. You need to:

• Update the API to add a new endpoint
• Update the frontend to consume that endpoint
• Write tests for both

With single-session Claude Code, you’d do this sequentially. With background sessions, you can run these in parallel:

Session 1 — Backend:

> Add a /users/preferences endpoint to the Express API that reads and writes user preference objects to the database. Include validation and error handling.
/bg

Session 2 — Frontend:

> Build a user preferences settings page in React that fetches from /users/preferences and lets users update their notification and display settings.
/bg

Session 3 — Tests:

> Write integration tests for the /users/preferences endpoint using Jest and Supertest. Cover happy path, invalid input, and auth failure cases.

Now three agents are working simultaneously. Your total wall clock time drops dramatically compared to running each task one after another.

Managing Complexity in Parallel Sessions

Parallel sessions are powerful but they can get messy. A few things to watch:

• File conflicts: If two agents are editing overlapping files, you’ll get conflicts. Plan your task split so agents work in separate parts of the codebase.
• Dependency ordering: If Session 2 needs something Session 1 hasn’t built yet, you’ll need to manage that timing manually. Claude Code doesn’t automatically coordinate between sessions.
• Context isolation: Each background session has its own context window. If you’ve given one session important information, you need to give it to other sessions separately.

---

Agent View: What You’re Actually Seeing

When Claude Code refers to “Agent View,” it’s describing the management interface for all your background sessions. This view shows you:

• A live status feed of what each agent is doing
• Any points where an agent has stopped and is waiting for your input
• Output logs you can scroll through
• The ability to jump into any session and provide guidance

Think of it as a control panel for your parallel workforce. You’re not watching every keystroke, but you can check in, course-correct, and redirect any agent at any point.

When Agents Need Human Input

Background agents don’t always run to completion without intervention. Common situations where an agent will pause and surface a question:

• It encounters an ambiguous design decision
• It hits an error it can’t resolve without more context
• It’s about to make a significant change (like deleting files) and wants confirmation
• It needs credentials or configuration values you haven’t provided

Claude Code will flag these in Agent View. You’ll see the session listed with a “waiting” status. Switch to it, answer the question, and the agent picks up where it left off.

---

Practical Tips for Getting More Out of Background Sessions

Write Better Starting Prompts

The quality of your initial prompt has a huge impact on how well a background session runs. When you send an agent to the background, you’re essentially setting it loose — so the more precise your instructions, the less likely it is to go off in the wrong direction.

Good background session prompts:

• Specify the files or directories the agent should work in
• Describe the expected output clearly (“add a function that returns X given Y”)
• Set constraints (“don’t change the database schema, only update the application layer”)
• Include context the agent can’t easily infer from the code itself

Poor background session prompts:

• Vague goals like “improve the codebase”
• Tasks that require ongoing decisions you haven’t pre-answered
• Work that touches shared files another agent is editing

Check In at Regular Intervals

A background agent working on a large task can drift. Check in every 15–30 minutes on longer tasks to make sure it’s heading in the right direction. It’s much easier to correct a small deviation early than to untangle a large one after the fact.

Use Session IDs to Stay Organized

When you have three or four background sessions running, the generic session IDs can be hard to track. Some versions of Claude Code let you add a label when you use /bg:

/bg --label "backend-api-endpoint"

This makes the sessions list much easier to scan.

---

Common Issues and How to Fix Them

The Agent Stopped Without Completing the Task

Check the session status in /sessions. If it shows “error,” switch to that session to see the error message. Common causes:

• The agent hit a file permission error
• A command it tried to run failed unexpectedly
• It ran into a loop and stopped itself

You can usually resolve this by switching to the session, explaining the error, and letting it continue.

Sessions Are Slowing Down My Machine

Running multiple parallel agents is computationally light on your local machine since the processing happens on Anthropic’s infrastructure — but each session does maintain an active connection and some local process overhead. If you’re running five or more simultaneous sessions and feeling performance degradation, close completed ones promptly.

I Accidentally Closed My Terminal

If you weren’t using tmux or a similar multiplexer, closed terminal sessions take your background agents with them. This is the main reason to use tmux when running background sessions for anything you care about. Set up a named tmux session before starting Claude Code:

tmux new-session -s claude-work

Then if you need to disconnect, use Ctrl+B, D to detach without killing the session.

An Agent Made Changes I Didn’t Want

Always work in a git repository when using background agents. Before starting a background session, make sure your working tree is clean. If an agent makes unwanted changes, you can review them with git diff and roll back with git checkout or git reset.

---

Expanding Multi-Agent Workflows with MindStudio

Claude Code’s background sessions are excellent for coding tasks, but they’re scoped to what Claude Code itself can do — file editing, terminal commands, and code reasoning. Once you need agents that go further — sending emails, updating CRMs, generating content, querying APIs, or triggering downstream processes — you need a different layer.

That’s where MindStudio fits cleanly into a multi-agent setup. MindStudio is a platform for building autonomous background agents that run on a schedule, respond to webhooks, or trigger from external events. Where Claude Code gives you a coding-focused agent you control from the terminal, MindStudio gives you agents that operate continuously in the background across business systems.

One particularly useful integration point is MindStudio’s Agent Skills Plugin, an npm SDK that lets any AI agent — including agents you build or orchestrate around Claude Code — call over 120 typed capabilities as simple method calls. Things like agent.sendEmail(), agent.searchGoogle(), or agent.runWorkflow() let your agents do more without you having to build and maintain each integration yourself.

For example, you could use Claude Code’s /bg command to run a background agent that refactors a codebase, while a separate MindStudio agent monitors a Slack channel for new feature requests, summarizes them, and drops them into a Notion backlog — all without you sitting in front of either terminal.

The two tools complement each other: Claude Code handles the deep coding work, MindStudio handles the broader process automation. You can try MindStudio free at mindstudio.ai.

---

Frequently Asked Questions

What is the /bg command in Claude Code?

The /bg command moves your current Claude Code session into the background, allowing the agent to continue working on its task while you start a new session or switch to a different one. The active session is added to Agent View, where you can monitor its status and switch back to it at any time.

How many background sessions can you run at once?

There’s no hard-coded limit enforced by the /bg command itself, but practical limits apply. API rate limits from Anthropic will affect how many sessions can make active requests simultaneously. For most development workflows, running two to four parallel sessions is manageable. Beyond that, coordination overhead tends to outweigh the time savings from parallelism.

Do background sessions stop if I close Claude Code?

If you close the terminal process running Claude Code, yes — background sessions end. To keep them running across terminal sessions, use a terminal multiplexer like tmux or screen. This lets you detach from the terminal and reconnect later without losing your active agents.

Can multiple background sessions edit the same files?

Technically yes, but this will cause conflicts. Each session operates independently and doesn’t know what other sessions are doing. If two agents modify the same file, you’ll end up with conflicting changes. Plan your parallel tasks so each agent works in a distinct part of the codebase.

How do I know when a background session is done?

Check the /sessions list to see status updates. Completed sessions show as “done” or “completed.” You can also configure Claude Code to send desktop notifications when a background session completes or needs attention, depending on your operating system and Claude Code version.

Is the /bg command the same as running Claude Code with nohup or &?

No. Running a terminal process with nohup or & detaches it from your terminal at the OS level, which is a different mechanism. /bg is a Claude Code-specific command that moves the session into Agent View while keeping it manageable within the Claude Code interface. Using both together — tmux plus /bg — gives you the most flexibility.

---

Key Takeaways

• The /bg command moves an active Claude Code session into Agent View, allowing it to keep running in the background while you start new sessions.
• You can run multiple parallel agents across different projects or parts of a codebase, significantly reducing total time on large tasks.
• Use /sessions to monitor background agents and /switch <id> to return to any of them.
• Use tmux to keep background sessions alive if you need to close or detach from your terminal.
• Plan parallel tasks carefully — agents don’t coordinate with each other, so file conflicts and dependency ordering are your responsibility.
• For workflows that extend beyond code — business automation, cross-tool integrations, scheduled agents — MindStudio pairs well with Claude Code’s background session model.