Claude Code Agent View: Background Sessions from One Screen

Open it from a shell:

1claude agents2claude agents --cwd ~/projects/my-app   # only this project's sessions

Type a prompt in the input at the bottom and press Enter: a new background session starts on that task and appears as a row. You can also dispatch straight from the shell without opening the view:

1claude --bg "investigate the flaky SettingsChangeDetector test"

To move a session you are already in to the background, run /background (or /bg), or press ← on an empty prompt, which backgrounds it and opens agent view with that row selected. /fork instead copies the conversation into a new background session while the original keeps running in your terminal.

claude agents accepts dispatch defaults such as --model, --effort, --permission-mode, and --agent, which apply to sessions you dispatch from that view.

Background sessions are not children of your terminal. A separate supervisor process runs them, so you can close agent view, close the shell, or start another interactive session, and dispatched work keeps going. The supervisor starts automatically the first time you need it.

To save resources, a session that has finished and stayed unattached for about an hour has its process stopped. Its conversation is kept, and it resumes when you reply or attach. If you want a session's process to stay up regardless, pin it with Ctrl+T.

Sessions are local: they run on your machine, are preserved across sleep, and stop if the machine shuts down. A session found dead long after its last activity, such as after a few days off, shows as stopped with ended while the background service was off, and asks before resuming its old conversation.

The state column is the point of agent view: you scan for yellow rows. Ctrl+S groups the list by state or by directory, Ctrl+R renames a session, and Ctrl+F finds one by name.

While agent view is open, Claude Code also sends a notification through your configured terminal notification channel when a local background session starts needing input, finishes, or fails, and fires the Notification hook with the agent_needs_input or agent_completed type, so you can forward those events elsewhere.

Three levels of interaction, from lightest to fullest:

• Peek: press Space on a row to open a panel with the latest output or the pending question. You can type a reply there without attaching.
• Attach: press Enter or → to turn the row into a full interactive session.
• Detach: press ← on an empty prompt, or run /exit, to return to agent view. Detaching never stops a background session.

One detail trips people up. When a session is waiting on a permission decision, typing a reply does not answer it; your message waits in the queue. To answer the permission dialog, attach with →.

Permission mode follows the session: backgrounding keeps the current mode, and a session dispatched from agent view starts in the mode the target directory configures through permissions.defaultMode, or the mode of the session you came from if none is set. bypassPermissions requires that you have accepted the bypass disclaimer.

Several background sessions in one repository would collide, so before editing files, Claude moves the session into an isolated git worktree under .claude/worktrees/. Parallel sessions can read the same checkout, but each writes to its own. When a session that isolated its work finishes, it commits, pushes its own branch (never main or master), and opens a draft pull request rather than asking first.

You can turn isolation off for a repository, for example one that is not under git or where you want sessions to edit the checkout directly:

1{2  "worktree": {3    "bgIsolation": "none"4  }5}

With isolation off, two sessions editing the same files will conflict, so only do this when you run one background session at a time in that repository.

Stop a session with Ctrl+X in agent view or claude stop <id>. Delete it with Ctrl+X twice (within two seconds) or claude rm <id>. The transcript stays on disk and remains available through claude --resume. Deletion keeps a worktree that still has unpushed commits or uncommitted changes and tells you why, so work is not silently destroyed.

The limits to plan around:

• Usage multiplies. Background sessions consume your subscription usage exactly like interactive ones, so ten in parallel use quota roughly ten times as fast as one. Rate limits apply.
• Sessions are local. They stop when the machine shuts down. For work that must continue with the laptop off, use cloud sessions instead.
• Research preview. Shortcuts and behaviour change between releases; the docs keep a long version history for that reason.

To turn agent view off entirely, set disableAgentView: true in settings or the CLAUDE_CODE_DISABLE_AGENT_VIEW environment variable.

Use a git repository with a test command.

1. Add .claude/worktrees/ to .gitignore. Run claude agents --cwd . and dispatch: "add a unit test for the parse function". 2. From another shell, run claude --bg "update the README's install section". 3. In a normal claude session, start a small task, then press ← on an empty prompt to background it. 4. In agent view, press Ctrl+S to group by state. When a row turns yellow, press Space to peek; if it is a permission prompt, attach with → to answer it. 5. When sessions complete, check git worktree list and the draft pull requests they opened. 6. Stop one session with Ctrl+X and delete another with Ctrl+X twice; confirm with claude --resume that the transcript is still available.

Pass criterion: three sessions ran at once without touching each other's files, you answered at least one prompt from agent view, and you can explain what deleting a session kept and removed.