Manage multiple agents with agent view changedagent-view
Nearest release: v2.1.267, published under an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+89added
Lines−24removed
From line
123
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits63to this page, all time
### Read session state from a script
The whole hunk
from line 123, old and new numbered
/
from line 123
123123
124124The terminal tab title shows the awaiting-input count while agent view is open: `2 awaiting input · claude agents` when sessions need input, or `claude agents` when none do.
125125
126To read session state from a script or another program, use [`claude agents --json`](#read-session-state-from-a-script) rather than the files under `~/.claude/jobs/`.
127
126128While agent view is open, Claude Code also sends a notification through your configured [terminal notification channel](/docs/en/terminal-config#get-a-terminal-bell-or-notification) when a local background session starts needing your input, finishes, or fails. Sessions that run on a schedule, such as [`/loop`](/docs/en/scheduled-tasks) sessions, notify only when they need your input. Notifications use the same [`preferredNotifChannel` setting](/docs/en/settings-reference#preferrednotifchannel) as the rest of Claude Code and fire the [`Notification` hook](/docs/en/hooks#notification) with the `agent_needs_input` or `agent_completed` type.
127129
128130Background sessions don't need any terminal open to keep working. A separate [supervisor process](#the-supervisor-process) runs them, so you can close agent view, close your shell, or start a new interactive session and your dispatched work keeps going.
from line 204
202204
203205Press `←` on an empty prompt, or run `/exit`, to detach and return to agent view, whether you opened the session from agent view or with `claude attach <id>` from your shell.
204206
207`←` also detaches while the [`/btw` overlay](/docs/en/interactive-mode#side-questions-with-%2Fbtw) is open. Requires Claude Code v2.1.257 or later. A side question that's still answering keeps running while you're away. The next time you attach, the overlay reopens with it, or with its answer.
208
205209On Windows, if you press `←` within about half a second of attaching, Claude Code shows `Ambiguous ←, press again to detach`, because in that window the terminal can redeliver a press from before you attached. Press `←` again to detach.
206210
207211`Ctrl+Z` also detaches but goes back to where you started instead: agent view if you attached from there, or your shell if you ran `claude attach`. Use `Ctrl+Z` when a dialog has focus and isn't responding to `←`.
from line 308
304308| `Ctrl+C` | Clear the input; press twice to exit |
305309| `?` | Show all shortcuts |
306310
311`Ctrl+S`, `Ctrl+T`, and `Ctrl+G` follow your [`keybindings.json`](/docs/en/keybindings). Rebind or unbind `Ctrl+S` and `Ctrl+T` with the `agents:switchView` and `agents:togglePin` actions in the [`Agents` context](/docs/en/keybindings#agents-actions), and `Ctrl+G` through the `Chat` context's `chat:externalEditor` binding. The other shortcuts in the table can't be rebound.
312
307313## Dispatch new agents
308314
309315You can dispatch new background sessions from agent view, send or copy an existing interactive session to the background, or start one directly from the shell.
from line 441
435441
436442When the backgrounded session later resumes or restarts, Claude Code restores the agent's system prompt and tool restrictions. It searches the session's own directory for the agent first, provided you've [trusted that workspace](/docs/en/permissions#project-allow-rules-and-workspace-trust), so a project-scoped agent still loads when the session is resumed from another directory. If the agent no longer exists, the session continues with the default tools and system prompt and its transcript opens with a [warning naming the agent](/docs/en/errors#session-agent-no-longer-available).
437443
444To continue an existing conversation in the background, pass its full session ID with `--resume`:
445
446```bash theme={null}
447claude --resume 1f0e2c9a-6d0b-4c11-9f39-2a77c1d4e8b5 --bg "pick up where you left off and finish the migration"
448```
449
450On Claude Code v2.1.257 or later, Claude Code either continues that session under the same ID, or starts a copy under a new ID and prints a `note:` line explaining why it couldn't continue in place. When the session continues in place, `claude agents` shows one row for it.
451
452When you combine `--bg` with `--continue`, a bare `--resume`, or `--resume` with a name or file path, Claude Code always starts such a copy. Add `--fork-session` to start a copy on purpose, without the note.
453
438454Pass `--name` to set the session's display name in agent view instead of the auto-generated one:
439455
440456```bash theme={null}
from line 529
513529
514530* Agent view removes it, including uncommitted changes, so commit what you want to keep first.
515531* `claude rm` keeps it, along with the session row, when it has uncommitted changes.
516* Neither agent view nor `claude rm` removes a worktree with commits Claude Code can't confirm are saved elsewhere, or one that another running session is using or has locked. Claude Code keeps the worktree and the session, and names the kept directory and the reason.
532* Neither agent view nor `claude rm` removes a worktree that another running session is using or has locked, and deleting again doesn't change that. Claude Code keeps the worktree and the session, and names the kept directory and the reason; in agent view, the session's row shows `not deleted`. Close the other session, then delete again.
533* When you delete a session whose worktree has commits that Claude Code can't confirm are saved elsewhere, Claude Code keeps the worktree and the session, and the message names the worktree's branch and how many commits are unpushed. The message also offers the two ways forward: push the commits, or delete again to discard them.
517534
518535 Commits on a remote don't block the delete. Neither do commits on the local copy of your `origin` remote's default branch, as long as that branch is checked out in your main checkout, the repository directory itself rather than a worktree.
519536
520 In agent view, a refused delete shows `not deleted` with the reason on the session's row. Push the commits, merge them into that default branch, or close the other session, then delete again.
537 After that refusal, you choose:
538
539 * To keep the commits, push them, or merge them into that default branch, then delete the session again.
540 * To discard them, delete the session again without pushing: press `Ctrl+X` twice on its row in agent view, or run the `claude rm <id> --discard-unpushed` command the refusal printed. This removes the session and the worktree along with its branch, discarding the unpushed commits and any uncommitted changes.
541
542 When you delete again, Claude Code discards only what the refusal showed: if the worktree has gained a commit since, Claude Code keeps it again and shows the updated state.
543
544 When another finished session's records also name the worktree, it stays when you delete again; push the commits, then delete again.
521545* A worktree git no longer recognizes, for example after `git worktree prune`, doesn't block the delete. Claude Code deletes the session and leaves the directory on disk.
522546
523547A worktree you created yourself and started the session inside is left in place either way.
from line 603
579603The [permission mode](/docs/en/permissions) depends on how you started the session:
580604
581605* **Backgrounded with `/bg` or `←`**: Claude Code keeps the permission mode the session was in, so one you switched to `acceptEdits` or `auto` stays there after detaching
582* **Dispatched from an agent view you opened with `←`**: the new session starts in the permission mode of the session you came from
606* **Dispatched from an agent view you opened with `←`**: the target's own configuration comes first, and the permission mode of the session you came from applies when nothing else sets one
583607* **Dispatched from `claude agents` started in a shell, or with `claude --bg`**: the new session starts the way a new `claude` session in that directory would, unless you dispatched it from an agent view you opened with [dispatch defaults](#dispatch-defaults). [Which permission mode a session starts in](/docs/en/permission-modes#which-mode-a-session-starts-in) lists the order
584608
609For a session you dispatch from an agent view opened with `←`, Claude Code takes the permission mode from the first of these that applies:
610
6111. The target directory's [`permissions.defaultMode`](/docs/en/settings-reference#permissions-defaultmode). Two source rules apply:
612 * `auto` and `bypassPermissions` [take effect only from managed settings, a `--settings` file, or `~/.claude/settings.json`](/docs/en/settings-reference#permissions-defaultmode).
613 * Claude Code refuses a `defaultMode` from the project's `.claude/settings.json` or `.claude/settings.local.json` that selects a more permissive mode than the session you came from was in.
6142. The permission mode of the session you came from
615
616When Claude Code refuses a source's mode as too permissive, the next source in the list decides. For example, if you dispatch from a plan-mode session into a directory whose checked-in settings ask for `acceptEdits`, the new session starts in plan mode. If you move that `defaultMode` to `~/.claude/settings.json`, it applies regardless of the permission mode of the session you came from.
617
618Permissiveness runs plan, then Manual and `dontAsk`, then `acceptEdits` and auto, which each count as more permissive than the other, then `bypassPermissions`.
619
585620#### Dispatch defaults
586621
587622To set defaults for every session you dispatch from agent view, pass any of `--permission-mode`, `--model`, `--effort`, or `--agent` when opening it:
from line 645
610645
611646Claude Code also keeps a name you set with [`/rename`](/docs/en/commands) or `Ctrl+R` across that restart, so you can still run [`claude --resume <name>`](/docs/en/sessions#name-your-sessions) to reach the session.
612647
648A prompt you stashed with [`Ctrl+S`](/docs/en/interactive-mode#general-controls) while attached is kept with the session too. Reopen the session after its process was stopped or restarted, and `Ctrl+S` restores the stashed text. Pasted content in the stash doesn't survive the restart.
649
613650### Settings, plugins, and MCP servers
614651
615652Agent view accepts the same configuration flags as `claude` for loading settings, plugins, MCP servers, and additional directories. Agent view applies `--settings` and `--plugin-dir` to itself and passes every configuration flag through to the sessions you dispatch from it, so a plugin or MCP server you load this way is available in those sessions.
from line 675
638675
639676Every background session has a short ID you can use from the shell. The ID is printed when you start a session with `claude --bg`, and each session's ID is its directory name under `~/.claude/jobs/`. These commands are useful for scripting or when you don't want to open agent view.
640677
641| Command | Purpose |
642| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
643| `claude agents` | Open agent view |
644| `claude agents --cwd <path>` | Open agent view scoped to sessions started under `<path>` |
645| `claude agents --json` | Print sessions as a JSON array and exit. See [List sessions as JSON](#list-sessions-as-json) |
646| `claude attach <id>` | Attach to a session in this terminal |
647| `claude logs <id>` | Print the session's recent output |
648| `claude stop <id>` | Stop a session. Also accepts `claude kill` |
649| `claude respawn <id>` | Restart a session, running or stopped, e.g. to pick up an updated Claude Code binary. The restarted session resumes its saved conversation; when none is on disk, it runs its original prompt again as a new conversation |
650| `claude respawn --all` | Restart every running session, e.g. to move all sessions onto an updated Claude Code binary at once |
651| `claude rm <id>` | Remove a session from the list, along with a worktree Claude created for it when that's safe to delete; see [What deleting a session removes](#what-deleting-a-session-removes). The conversation transcript stays on your local machine and remains available through `claude --resume` |
652| `claude daemon status` | Print the [supervisor's](#the-supervisor-process) state, version, socket directory, and worker count |
653| `claude daemon stop --any` | Stop the supervisor process and the background sessions it hosts. Pass `--keep-workers` to leave background sessions running so the next supervisor reconnects to them. The next `claude agents` or `claude --bg` starts a fresh supervisor |
678| Command | Purpose |
679| :--------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
680| `claude agents` | Open agent view |
681| `claude agents --cwd <path>` | Open agent view scoped to sessions started under `<path>` |
682| `claude agents --json` | Print sessions as a JSON array and exit. See [List sessions as JSON](#list-sessions-as-json) |
683| `claude attach <id>` | Attach to a session in this terminal |
684| `claude logs <id>` | Print the session's recent output |
685| `claude stop <id>` | Stop a session. Also accepts `claude kill` |
686| `claude respawn <id>` | Restart a session, running or stopped, e.g. to pick up an updated Claude Code binary. The restarted session resumes its saved conversation; when none is on disk, it runs its original prompt again as a new conversation |
687| `claude respawn --all` | Restart every running session, e.g. to move all sessions onto an updated Claude Code binary at once |
688| `claude rm <id>` | Remove a session from the list, along with a worktree Claude created for it when that's safe to delete; see [What deleting a session removes](#what-deleting-a-session-removes). The conversation transcript stays on your local machine and remains available through `claude --resume` |
689| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | Delete a session whose delete was refused over unpushed commits, discarding the worktree along with its branch and commits. Pass the exact value that refusal printed; see [What deleting a session removes](#what-deleting-a-session-removes). Requires v2.1.260 or later |
690| `claude daemon status` | Print the [supervisor's](#the-supervisor-process) state, version, socket directory, and worker count |
691| `claude daemon stop --any` | Stop the supervisor process and the background sessions it hosts. Pass `--keep-workers` to leave background sessions running so the next supervisor reconnects to them. The next `claude agents` or `claude --bg` starts a fresh supervisor |
654692
655693### List sessions as JSON
656694
from line 700
662700| :------------------------- | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
663701| `cwd`, `kind`, `startedAt` | Always | The working directory, `interactive` or `background`, and the start time in Unix milliseconds |
664702| `id` | Background sessions | Short ID, usable with `claude attach`, `claude logs`, and `claude stop` |
665| `state` | Background sessions | One of `working`, `blocked`, `done`, `failed`, or `stopped` |
666| `pid`, `status` | While the process is alive | Process ID and current status |
703| `state` | Background sessions | One of `working`, `blocked`, `done`, `failed`, or `stopped`. See [Read session state from a script](#read-session-state-from-a-script) for what each value means |
704| `pid`, `status` | While the process is alive | Process ID and one of `busy`, `waiting`, or `idle` |
667705| `waitingFor` | When `status` is `waiting` | What the session is blocked on: `permission prompt` for an approval, `input needed` for a question from Claude or an MCP server's input request, `sandbox request`, `worker request`, or `dialog open` |
668706| `sessionId`, `name` | When set | `sessionId` is the full session UUID, usable with [`claude --resume`](/docs/en/sessions). An interactive session's `name` is its [default display name](/docs/en/sessions#name-your-sessions) until you name the session or accept a plan in it |
669707
708### Read session state from a script
709
710`claude agents --json` is the supported way to read session state from outside Claude Code, for example from a status bar, a scheduler, or another Claude session that supervises background work. Poll `claude agents --json --all`, which keeps listing sessions whose process has exited, and read each entry's `state`, `status`, and `waitingFor`.
711
712| `state` | What it means |
713| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
714| `working` | A turn is running, or the session is between steps of work it drives on its own, such as a [`/loop`](/docs/en/scheduled-tasks) iteration or a wait on CI. `status` tells you whether its process is `busy` right now |
715| `blocked` | The session is waiting on you: a question it asked, a permission or sandbox decision, an error only you can clear such as an expired login, or its first prompt if you started it without one. When the wait is an open prompt in a live process, `waitingFor` names it |
716| `done` | The last turn finished what you asked for and the session is ready for your next prompt, whether or not its process is still alive |
717| `failed`, `stopped` | The task ended with an error, or the session was stopped |
718
719A session that finished its turn and is waiting for your next instruction reads `done`, not `blocked`. `blocked` always means the session needs something from you before it can continue.
720
721The files under `~/.claude/jobs/<id>/` are not a stable interface. Values that a session or another program writes to `state`, `detail`, `tempo`, or `needs` are replaced on the next update.
722
723If you want a session to report progress in its own words, have it write a file of its own, for example under `$CLAUDE_JOB_DIR/tmp`, instead of editing `state.json`.
724
670725## How background sessions are hosted
671726
672727Claude Code treats every session listed in agent view as a background session, whether or not you're currently attached to it. By contrast, a session started by running `claude` directly is tied to that terminal and ends when it closes, unless you [send it to the background](#from-inside-a-session).
from line 747
692747
693748Session state is stored under your Claude Code config directory. If you set [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars), the supervisor uses that directory instead of `~/.claude` and runs as a separate instance with its own sessions.
694749
695| Path | Contents |
696| :------------------------------- | :---------------------------------------------------------------------------------------------------------- |
697| `~/.claude/daemon.log` | Supervisor log |
698| `~/.claude/daemon/roster.json` | List of running background sessions, used to reconnect after a restart |
699| `~/.claude/jobs/<id>/state.json` | Per-session state shown in agent view |
700| `~/.claude/jobs/<id>/tmp/` | Per-session scratch directory. Writes here don't prompt for permission. Removed when the session is deleted |
750| Path | Contents |
751| :------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
752| `~/.claude/daemon.log` | Supervisor log |
753| `~/.claude/daemon/roster.json` | List of running background sessions, used to reconnect after a restart |
754| `~/.claude/jobs/<id>/state.json` | Per-session state shown in agent view. Read it through [`claude agents --json`](#read-session-state-from-a-script) instead of parsing the file |
755| `~/.claude/jobs/<id>/tmp/` | Per-session scratch directory. Writes here don't prompt for permission. Removed when the session is deleted |
701756
702757Each background session has the `CLAUDE_JOB_DIR` environment variable set to its `~/.claude/jobs/<id>` directory, so shell commands the session runs can write temporary files to `$CLAUDE_JOB_DIR/tmp` without colliding with parallel sessions.
703758
from line 923
868923
869924| Version | Change |
870925| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
926| v2.1.260 | When you [background a session](#from-inside-a-session), your other sessions' [agent listing](/docs/en/cross-session-messaging#see-which-sessions-claude-can-reach) shows the conversation once, as its background session, and their messages to it no longer reach the terminal you moved it from. Before this release, that terminal could stay listed as a second interactive session under the conversation's name, and a session that had messaged the conversation before the move kept delivering to that terminal. |
927| v2.1.260 | When a [delete is refused over unpushed commits](#what-deleting-a-session-removes), the message names the worktree's branch and how many commits are unpushed, and deleting the session again discards the worktree and its commits. Before this release, the refusal said only `worktree has commits that are not pushed anywhere`, deleting again was refused the same way, and deleting the session required pushing the commits or removing the worktree by hand. |
928| v2.1.257 | `←` [detaches from an attached session while the `/btw` overlay is open](#attach-to-a-session), even mid-answer, and the overlay reopens when you next attach. Before this release, `←` didn't detach while the overlay was open. |
929| v2.1.257 | When you run [`claude --resume <session-id> --bg`](#from-your-shell), Claude Code continues that session under its own ID, or starts a copy under a new ID and prints a `note:` line explaining why. `--continue`, a bare `--resume`, and `--resume` with a name or path start a copy with the same note. Before this release, `--resume` with `--bg` always started a copy under a new ID and said nothing. |
930| v2.1.257 | When you dispatch a session from an agent view you opened with `←`, Claude Code starts it in [the permission mode the target directory configures](#permission-mode) through `permissions.defaultMode`. When the directory doesn't set one, the permission mode of the session you came from applies. Before this release, the dispatched session always started in the permission mode of the session you came from, overriding it. |
931| v2.1.257 | `Ctrl+S`, `Ctrl+T`, and `Ctrl+G` in agent view [follow your `keybindings.json`](#keyboard-shortcuts): `Ctrl+S` and `Ctrl+T` through the `Agents` context's `agents:switchView` and `agents:togglePin` actions, and `Ctrl+G` through the `Chat` context's `chat:externalEditor` binding. Before this release, agent view ignored `keybindings.json` and these keys were fixed. |
932| v2.1.257 | Starting the [background service](#the-supervisor-process) recovers from two failure causes. On a macOS npm installation, a start during a self-update [waits for the install](/docs/en/errors#eacces-when-starting-a-background-session) instead of running the placeholder that npm lays down while replacing the binary. On Windows, a stale `daemon.lock` written before the machine last booted, or whose recorded process ID now belongs to a different process, is replaced. Before this release, the macOS start failed with `Error: claude native binary not installed.` during the install window, and the Windows lock made every start fail with [`exited before it became reachable`](/docs/en/errors#background-service-exited-before-it-became-reachable) until you deleted `~/.claude/daemon.lock`. |
933| v2.1.257 | When you open or dispatch a background session while another Claude Code process is downloading an npm update, Claude Code [keeps waiting up to two minutes](/docs/en/errors#eacces-when-starting-a-background-session) while the install runs, then fails saying `Claude Code is being updated by npm on this machine`. Before this release, the wait stopped at ten seconds, so the open failed with `Couldn't start the background service` while the download was still running. |
934| v2.1.257 | A background session holding a [cross-session message](/docs/en/cross-session-messaging#control-inbound-messages) for your approval shows `approve message from` on its `Needs input` row, with the sender's address and the name the sender claims. Before this release, the row moved to `Needs input` but kept its previous text, so nothing in `claude agents` named the waiting message or its sender. |
935| v2.1.257 | A prompt stashed with `Ctrl+S` inside an opened background session [is kept with the session](#what-persists-across-restarts), so `Ctrl+S` restores it after the session's process is stopped and started again. Before this release, the stash lived only in the running process and was lost when the session went idle long enough for its process to stop, or when it was stopped and then reopened. |
871936| v2.1.251 | In a background session that hasn't [moved into a worktree](#how-file-edits-are-isolated), Claude and the subagents it spawns can edit files inside a linked git worktree. |
872937| v2.1.251 | Claude Code forwards a cloud provider gateway exported in the shell you dispatch from, such as `ANTHROPIC_VERTEX_BASE_URL` or `ANTHROPIC_BEDROCK_BASE_URL` with its auth-bypass flag, to [the session's worker](#llm-gateway) under the same conditions as `ANTHROPIC_BASE_URL`. Before this release, if you backgrounded or dispatched from a shell authenticated only through such a gateway, every request the session made failed, because the endpoint and flag were dropped from its environment. |
873938| v2.1.251 | When a background session starts while another Claude Code process is refreshing a [plugin marketplace](/docs/en/plugin-marketplaces), such as a sibling session running the [marketplace auto-update](/docs/en/discover-plugins#configure-auto-updates), Claude Code keeps that marketplace's plugins available. Before this release, such a session could start without any of that marketplace's skills, agents, hooks, and MCP servers and stay that way for its whole run. |
No line in this hunk matches that.