How to Run a Claude Code Session in the Background: /background, claude --bg, Agent View, and Getting Back to It

"Run Claude Code in the background" means two different things, and most of the confusion around it comes from mixing them up. The first is a background task: one long shell command, say a test suite, moved out of the way with Ctrl+B so Claude can keep working. The second is a background session: the whole Claude Code conversation detached from your terminal and kept running by a supervisor process, so you can close the window, start something else, and come back to it later. This post is about the second one. For the first, see our guide to background tasks.

Everything below comes from the Claude Code documentation for agent view, which is the feature background sessions live under. It is in research preview, so flags and shortcuts can change between versions; if a command is rejected with unknown option, run claude update first.

What a background session is

A normal Claude Code session is a process tied to your terminal. Close the terminal, and the session ends. A background session is the same conversation handed to a supervisor process that runs it without a terminal attached. You can close agent view, close your shell, or start new sessions, and the work continues. The state survives auto-updates and supervisor restarts, and sessions are preserved across sleep and reconnect on wake. The one thing they do not survive is a shutdown: background sessions are local, and they stop if the machine is turned off.

Agent view, opened with claude agents, is the screen that manages them: one row per session, showing what each is doing, which ones need your input, and which are done.

Three ways to send a session to the background

1. From inside a running session

You are mid-conversation, Claude has started a long task, and you want your terminal back. Press ← on an empty prompt. The current session moves to the background and agent view opens with its row selected; press Esc to return to the conversation. If you would rather type it, /background (or /bg) does the same thing, and /bg <prompt> runs that prompt first and then moves the conversation to the background.

There is also /fork [prompt], which copies the conversation into a new background session while the original keeps running in your terminal. That is the right tool when you want to try a different approach without losing the thread you are on.

2. When you exit with work still running

If you quit a session while background work is running, Claude Code shows a Background work is running dialog with a Move to background and exit option. Choosing it hands the session to the supervisor instead of killing it. Some in-flight work, such as a running monitor, cannot carry over; in that case you see a Background this session? dialog first so you can decide.

3. From the shell, without ever attaching

# start a background session straight from your shell
claude --bg "run the full test suite and fix anything that fails"

# give it a name you will recognise in agent view
claude --bg --name "test-fixes" "run the full test suite and fix anything that fails"

# continue an existing session in the background
claude --resume <session-id> --bg

# a plain shell job with no Claude session at all
claude --bg --exec 'pytest -x'

--bg (long form --background) cannot be combined with -p or --print; headless one-shot runs and background sessions are different tools. Inside agent view itself, typing a prompt in the bottom input and pressing Enter dispatches a new background session, and prefixing it with ! runs a shell command as a background job.

Getting back to it

Open claude agents, move to the row with ↑ and ↓, and press Space to peek at the latest output or the pending question without attaching; you can reply inline from the peek panel. Press Enter or → to attach to the full session, and ← on an empty prompt to detach again. Ctrl+Z detaches and returns you to wherever you started. Detaching never stops a session. To end one from inside it, run /stop.

claude agents              # the overview
claude agents --cwd ~/code  # only sessions started under that directory
claude agents --json        # machine-readable list (add --all for completed)
claude attach <id>          # attach from the shell
claude logs <id>            # read a session's output
claude stop <id>            # stop it (alias: kill)
claude rm <id>              # remove the row
claude daemon status        # is the supervisor running?

The hour rule, and pinning

A background session that has finished, or is waiting for your next message, and has been unattached for about an hour is stopped to free resources. Its conversation stays on disk and it resumes on the next attach or reply, so nothing is lost; but if you want a session's process kept alive regardless, pin it with Ctrl+T in agent view. Sessions that exit unexpectedly are restarted automatically; a session you stopped yourself is marked stopped and left alone.

If the machine was off for a while, what you see depends on timing. Within 48 hours of a session's last progress it shows as failed, and attaching or replying restarts it from where it left off. Past 48 hours it shows as stopped with ended while the background service was off; press Enter on the row twice to resume its saved conversation.

Worktrees: the part that surprises people

By default, each background session is isolated in its own git worktree under .claude/worktrees/, so parallel sessions do not edit the same working copy. That is the right default for parallel work, and a trap if you expected the background session to keep editing the files in your main checkout. Two consequences: commit or push before deleting a session that edited files in its worktree, because the worktree can be removed with the session (uncommitted or unpushed work blocks the delete, with --discard-unpushed and --force-remove-worktree as the overrides); and if you want the old behaviour, set worktree.bgIsolation to "none" in settings so background sessions edit the working copy directly.

Permissions and notifications

A background session asks for permission exactly like a foreground one; it just asks in a place you are not looking. Agent view shows a row as needing input, the terminal tab title shows a count of sessions awaiting input, and while agent view is open Claude Code notifies you through your normal terminal notification channel when a local background session needs input, completes, or fails. Those notifications use preferredNotifChannel and fire the Notification hook with the agent_needs_input or agent_completed type, which means anything you have built on Claude Code hooks or the preferredNotifChannel setting already works for background sessions.

One more permission note: dispatching with --permission-mode bypassPermissions requires having accepted the bypass disclaimer once by running claude --dangerously-skip-permissions interactively. And on macOS the background session host is its own process, so it asks for access to Desktop, Documents and Downloads separately from your terminal; an Operation not permitted on one of those folders is fixed under Privacy & Security in System Settings, not in Claude Code.

Settings and environment variables

• disableAgentView (setting) or CLAUDE_CODE_DISABLE_AGENT_VIEW: turn agent view off entirely.
• leftArrowOpensAgents in /config: disable the ← shortcut if you keep hitting it by accident.
• CLAUDE_DISABLE_ADOPT=1: stop in-flight work on exit instead of carrying it to the background.
• CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1: stop background work when the process exits.
• CLAUDE_JOB_DIR: set automatically in each session to its ~/.claude/jobs/<id> directory; use $CLAUDE_JOB_DIR/tmp for scratch files.
• CLAUDE_CONFIG_DIR: a separate config dir gives you a separate supervisor with its own sessions.

Session state lives under ~/.claude/ in daemon.log, daemon/roster.json and jobs/<id>/state.json. Read it with claude agents --json rather than parsing those files; their format is not stable.

What it costs

Background sessions use your subscription quota exactly like interactive ones. Ten sessions in parallel burn usage roughly ten times as fast as one, and nothing about being in the background makes a session cheaper. If you are using --bg to fan out work, the effort level you dispatch with (claude agents --effort sets the default for sessions started from the view) is the lever that matters.

Background task or background session?

• One long command, Claude should keep going meanwhile: background task. Press Ctrl+B or ask Claude to run it in the background.
• Claude is working on something long and you want your terminal, or you want to close the laptop lid and come back: background session. Press ← or /bg.
• Several independent jobs at once: several background sessions, dispatched from claude agents or with claude --bg, each in its own worktree.
• A one-shot script with no interaction: not a background session at all; use headless mode with -p.

The thing a background session does not do is tell your phone. Agent view notifies the terminal it is open in. If the reason you backgrounded the session was to walk away from the machine, you still need something that reaches you where you are.