6 6
7> Dispatch and manage many Claude Code sessions from one screen. Agent view shows what every session is doing and which ones need your input.7> Dispatch and manage many Claude Code sessions from one screen. Agent view shows what every session is doing and which ones need your input.
8 8
9Agent view, opened with `claude agents`, is one screen for all your background sessions: what's running, what needs your input, and what's done. Dispatch new sessions, watch their state at a glance instead of scrolling through transcripts, and step in only when one needs you. Sessions keep running in the background without a terminal attached.9Agent view, opened with `claude agents`, is one screen for all your background sessions: what's running, what needs your input, and what's done. Dispatch new sessions, watch their state at a glance instead of scrolling through transcripts, and step in only when one needs you. Each background session is a full Claude Code conversation that keeps running without a terminal attached, so you can open it, reply, and leave whenever you want.
10 10
11Use agent view when you have several independent tasks Claude can work on at once, such as fixing a bug, reviewing a pull request, or investigating a log. When you want to work through a problem together, attach to a session and use Claude Code interactively as usual.11<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-light.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=7a186c96ed47d6700d084d77e786be65" className="dark:hidden" alt="Agent view in a terminal: the header shows Claude Code v2.1.140, the model, the working directory, and a summary count. Sessions are grouped under Needs input, Working, and Completed, with a dispatch input at the bottom and a footer of keyboard hints." width="1772" height="780" data-path="images/agent-view-light.png" />
12 12
13Sessions in agent view run independently and report only to you. To compare with subagents, agent teams, and worktrees, see [Run agents in parallel](/en/agents).13<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-dark.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=a5bed7434bae368faea3a8f023b52aa2" className="hidden dark:block" alt="Agent view in a terminal: the header shows Claude Code v2.1.140, the model, the working directory, and a summary count. Sessions are grouped under Needs input, Working, and Completed, with a dispatch input at the bottom and a footer of keyboard hints." width="1772" height="780" data-path="images/agent-view-dark.png" />
14
15Use agent view when you have several independent tasks Claude can work on without you watching every step. Dispatch a bug fix, a pull request review, and a flaky-test investigation as three rows, keep working in another window, and check back when a row shows it needs you or has a result.
16
17When you want to work more directly in any agent's session, attach to the row to enter the full conversation.
18
19To compare agent view with subagents, agent teams, and worktrees, see [Run agents in parallel](/en/agents).
14 20
15<Note>21<Note>
16 Agent view is a research preview and requires Claude Code v2.1.139 or later. Check your version with `claude --version`. The interface and keyboard shortcuts may change as the feature evolves, and administrators can disable agent view for an organization with the [`disableAgentView`](#how-background-sessions-are-hosted) managed setting.22 Agent view is in research preview and requires Claude Code v2.1.139 or later. Check your version with `claude --version`. The interface and keyboard shortcuts may change as the feature evolves.
17</Note>23</Note>
18 24
19This page covers:25This page covers:
20 26
21* [Quick start](#quick-start)27* [Quick start](#quick-start): give Claude a task to work on in the background, check on it, and step in when needed
22* [Monitor sessions with agent view](#monitor-sessions-with-agent-view), including state icons, peeking and replying, attaching, organizing, and keyboard shortcuts28* [Monitor sessions with agent view](#monitor-sessions-with-agent-view), including state icons, peeking and replying, attaching, organizing, and keyboard shortcuts
23* [Dispatch new agents](#dispatch-new-agents) from agent view, from inside a session, or from the shell29* [Dispatch new agents](#dispatch-new-agents) from agent view, from inside a session, or from your shell
24* [Manage sessions from the shell](#manage-sessions-from-the-shell)30* [Manage sessions from the shell](#manage-sessions-from-the-shell)
25* [How background sessions are hosted](#how-background-sessions-are-hosted) by the supervisor process31* [How background sessions are hosted](#how-background-sessions-are-hosted) by the supervisor process
26 32
27## Quick start33## Quick start
28 34
29This walkthrough opens agent view, dispatches a session, replies from the peek panel, and attaches for the full conversation.35This walkthrough covers the core agent view loop: dispatch a task, watch its row update as Claude works, peek to check on it and reply, and attach for the full conversation. The session you dispatch keeps running after you close agent view, so you can leave and come back to it.
30 36
31<Steps>37<Steps>
32 <Step title="Open agent view">38 <Step title="Open agent view">
36 claude agents42 claude agents
37 ```43 ```
38 44
39 Agent view opens with an input at the bottom and a table that fills in as sessions start. Press `Esc` at any time to exit. Your sessions keep running.45 Agent view opens with an input at the bottom and a table that fills in as sessions start. Press `Esc` at any time to return to your shell. Your sessions keep running while you're away and reappear the next time you open agent view.
40 </Step>46 </Step>
41 47
42 <Step title="Dispatch a session">48 <Step title="Dispatch a session">
43 Type a prompt in the input and press `Enter`. A new session starts and appears as a row showing whether it's working, waiting on you, or done. Repeat to run several sessions in parallel. Each one uses your subscription quota independently, so see [Limitations](#limitations) before dispatching many at once.49 Type a prompt describing a task and press `Enter`. A new background session starts on that task and appears as a row showing whether it's working, waiting on you, or done. The new session uses the model shown in the agent view header and the same [permission mode](#permission-mode-and-settings) you'd get running `claude` in that directory.
50
51 Every prompt you enter here starts its own new session. Typing another prompt and pressing `Enter` launches a second session alongside the first rather than sending a follow-up to it. You can run several in parallel this way.
52
53 Each session uses your subscription quota independently, so see [Limitations](#limitations) before dispatching many at once.
44 </Step>54 </Step>
45 55
46 <Step title="Peek and reply">56 <Step title="Peek and reply">
47 Select a row with the arrow keys and press `Space` to see what the session is doing or what it needs from you. Type a reply and press `Enter` to send it without leaving agent view.57 Select a row with the arrow keys and press `Space` to open the peek panel. It shows the session's most recent output, or the question it's waiting on, rather than the full transcript. Type a reply and press `Enter` to send it without leaving agent view.
48 </Step>58 </Step>
49 59
50 <Step title="Attach and detach">60 <Step title="Attach and detach">
51 Press `Enter` or `→` on a row to attach when you want the full conversation. The session takes over the terminal exactly as if you had run `claude`. Press `←` on an empty prompt to detach and return to the table.61 Press `Enter` or `→` on a row to attach when you want the full conversation. The session takes over the terminal exactly as if you had run `claude`. Press `←` on an empty prompt to detach and return to the table.
52 </Step>62 </Step>
53</Steps>
54 63
55To bring an existing interactive session into agent view, run `/bg` inside it, or press `←` on an empty prompt to background the session and open agent view in one step. The session keeps running in the background and appears as a row. To start a new background session directly from the shell, run `claude --bg "<prompt>"`.64 <Step title="Bring an existing session in">
65 To move a session you already have open into agent view, run `/bg` inside it, or press `←` on an empty prompt to background it and open agent view in one step. The session keeps running and appears as a row alongside the ones you dispatched.
66 </Step>
67</Steps>
56 68
57You can use `claude agents` as your primary entry point instead of `claude`: dispatch every task from agent view, attach when you want the full conversation, and press `←` to return to the table.69You can use `claude agents` as your primary entry point instead of `claude`: dispatch every task from agent view, attach when you want the full conversation, and press `←` to return to the table.
58 70
60 72
61Run `claude agents` to open agent view. It takes over the full terminal and lists every session grouped by state, with pinned sessions and the ones that need you at the top. Each row shows the session's name, current activity, and how long ago it last changed.73Run `claude agents` to open agent view. It takes over the full terminal and lists every session grouped by state, with pinned sessions and the ones that need you at the top. Each row shows the session's name, current activity, and how long ago it last changed.
62 74
63The list covers every background session under your [config directory](#how-background-sessions-are-hosted), regardless of which project or worktree it's working in, so a session started in one repository and another started in a different worktree both appear together. Interactive sessions you have open in other terminals don't appear until you [background them](#from-inside-a-session), and [subagents](/en/sub-agents) running inside a session aren't listed as separate rows.75The list shows every background session you've started, across all your projects. A session working in one repository and another in a different worktree both appear here, regardless of which directory you opened agent view from. Interactive sessions you have open in other terminals don't appear until you [background them](#from-inside-a-session). [Subagents](/en/sub-agents) and [teammates](/en/agent-teams) a session spawns aren't listed as separate rows.
64 76
65```text theme={null}77```text theme={null}
66Pinned78Pinned
67 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m79 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m
68 80
69Ready for review81Ready for review
70 ∙ jump physics github.com/anthropics/example/pull/2048 ● 2h82 ∙ jump physics github.com/example/game/pull/2048 ● 2h
71 83
72Needs input84Needs input
73 ✻ power-up design needs input: double jump or wall climb? 1m85 ✻ power-up design needs input: double jump or wall climb? 1m
82 … 6 more94 … 6 more
83```95```
84 96
85Each row's icon carries two signals. The indicator tells you the session's state, and the icon's shape tells you whether the underlying process is still running. The states are:97### Read session state
98
99Each row starts with an icon whose color and animation show the session's state:
100
101| State | Icon shows as | What it means |
102| :---------- | :------------ | :----------------------------------------------------------------------- |
103| Working | Animated | Claude is actively running tools or generating a response |
104| Needs input | Yellow | Claude is waiting on a specific question or permission decision from you |
105| Idle | Dimmed | The session has nothing to do and is ready for your next prompt |
106| Completed | Green | The task finished successfully |
107| Failed | Red | The task ended with an error |
108| Stopped | Grey | The session was stopped with `Ctrl+X` or `claude stop` |
86 109
87| Indicator | State | What it means |110Separately, the icon's shape shows whether the underlying process is running:
88| :-------- | :---------- | :--------------------------------------------------------------------------- |
89| Animated | Working | Claude is actively running tools or generating a response |
90| Yellow | Needs input | Claude is waiting for your input, usually a permission decision or an answer |
91| Dimmed | Idle | The session is waiting for input but isn't blocked on a specific question |
92| Green | Completed | The task finished successfully |
93| Red | Failed | The task ended with an error |
94| Grey | Stopped | The session was stopped with `Ctrl+X` or `claude stop` |
95 111
96The icon's shape tells you whether the underlying process is still running. A `✻`, or an animated `✽` while Claude is working, means the session is alive and you can reply to it immediately. A `∙` means the process has exited, but you can still peek, reply, or attach: Claude restarts the session from where it left off. A `✢` is a [`/loop`](/en/commands) session sleeping between iterations, with the row showing its run count and a countdown to the next iteration.112| Shape | What it means |
113| :------------------ | :---------------------------------------------------------------------------------------------------------------- |
114| `✻` or animated `✽` | The session process is alive and replies immediately |
115| `∙` | The process has exited. You can still peek, reply, or attach, and Claude restarts from where it left off |
116| `✢` | A [`/loop`](/en/scheduled-tasks) session sleeping between iterations. The row shows its run count and a countdown |
97 117
98Background sessions don't need any terminal open to keep working. A separate [supervisor process](#how-background-sessions-are-hosted) runs them, so you can close agent view, close your shell, or start a new interactive session and your dispatched work keeps going.118Background 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.
99 119
100Sessions persist on disk: closing your terminal or an auto-update doesn't lose them, and reopening `claude agents` shows them all. If your machine sleeps or shuts down, running sessions stop; restart them with `claude respawn --all`.120Session state persists on disk through auto-updates and supervisor restarts. If your machine sleeps or shuts down, running sessions stop; restart them with `claude respawn --all`.
101 121
102The one-line summary in each row is generated by your configured [Haiku-class model](/en/model-config) so the row can tell you what the session is doing, what it needs, or what it produced without opening the transcript. While a session is actively working, the summary refreshes at most once every 15 seconds, plus once when each turn ends. Each refresh is one short Haiku-class request through your normal provider, billed and handled under the same [data usage terms](/en/data-usage) as the session itself.122### Row summaries
123
124The one-line summary in each row is generated by a [Haiku-class model](/en/model-config) so the row can tell you what the session is doing, what it needs, or what it produced without opening the transcript. While a session is actively working, the summary refreshes at most once every 15 seconds, plus once when each turn ends.
125
126Each refresh is one short Haiku-class request through your normal provider, billed and handled under the same [data usage terms](/en/data-usage) as the session itself.
127
128### Pull request status
103 129
104When a session opens a pull request, a status dot appears at the right edge of the row, linked to the pull request in terminals that support hyperlinks. When the session has opened more than one pull request, the count appears before the dot and the color reflects whichever one most needs attention.130When a session opens a pull request, a status dot appears at the right edge of the row, linked to the pull request in terminals that support hyperlinks. When the session has opened more than one pull request, the count appears before the dot and the color reflects whichever one most needs attention.
105 131
122 148
123### Attach to a session149### Attach to a session
124 150
125Press `Enter` or `→` on a selected row to attach, or press `Alt+1` through `Alt+9` to attach directly to the Nth session in the focused group. Agent view is replaced by the full interactive session, exactly as if you had run `claude` in that directory. When you attach, Claude posts a short recap of what happened while you were away.151Press `Enter` or `→` on a selected row to attach. Agent view is replaced by the full interactive session, exactly as if you had run `claude` in that directory. When you attach, Claude posts a short recap of what happened while you were away.
126 152
127While attached, the session behaves like any other Claude Code session: every [command](/en/commands), keyboard shortcut, and feature works.153While attached, the session behaves like any other Claude Code session: every [command](/en/commands), keyboard shortcut, and feature works.
128 154
134 160
135### Organize the list161### Organize the list
136 162
137Agent view groups sessions by state, with sessions that need input above sessions that are working or done. Press `Ctrl+S` to switch to grouping by directory instead. Your choice is saved across runs. Within a group, pin a session to the top with `Ctrl+T`, reorder with `Shift+↑` and `Shift+↓`, or press `Enter` on a group header to collapse it. To remove a session, press `Ctrl+X` to stop it and `Ctrl+X` again within two seconds to delete it. Pressing `Ctrl+X` on a group header deletes every session in that group after confirmation.163Agent view groups sessions so the ones that need input are at the top, with `Ready for review` and `Needs input` above `Working` and `Completed`. These group names don't map one-to-one to the [states](#read-session-state) above: a session moves to `Ready for review` when it has an open pull request, and `Completed` collects finished, failed, and stopped sessions together. Press `Ctrl+S` to group by directory instead. Your choice persists across runs.
164
165Within a group:
166
167* Press `Ctrl+T` to pin a session to the top
168* Press `Shift+↑` or `Shift+↓` to reorder sessions
169* Press `Ctrl+R` to rename a session
170* Press `Enter` on a group header to collapse it
138 171
139Older completed sessions fold into a "… N more" row to keep the list short. Failures and sessions with an open pull request always stay visible.172To remove a session from the list, press `Ctrl+X` to stop it and `Ctrl+X` again within two seconds to delete it. Pressing `Ctrl+X` on a group header deletes every session in that group after confirmation.
140 173
141### Filter the list174Deleting removes the session from agent view and cleans up its [worktree](#how-file-edits-are-isolated), including any uncommitted changes in it, so push or commit work you want to keep before deleting. The conversation transcript stays on disk and remains available through `claude --resume`.
175
176Older completed sessions fold into a `… N more` row to keep the list short. Failures and sessions with an open pull request always stay visible.
177
178### Filter sessions
142 179
143Type in the dispatch input to filter instead of dispatching:180Type in the dispatch input to filter instead of dispatching:
144 181
145| Filter | Shows |182| Filter | Shows |
146| :---------------------- | :-------------------------------------------------------------------------- |183| :---------------------- | :------------------------------------------------------------------------------------------------------- |
147| `a:<name>` | Sessions running the named agent |184| `a:<name>` | Sessions running the named agent |
148| `s:<state>` | Sessions in the given state, such as `s:blocked` for sessions that need you |185| `s:<state>` | Sessions in the given state, such as `s:working`. Also accepts `s:blocked` for everything waiting on you |
149| `#<number>` or a PR URL | The session working on that pull request |186| `#<number>` or a PR URL | The session working on that pull request |
150 187
151### Keyboard shortcuts188### Keyboard shortcuts
152 189
153Press `?` in agent view to see every shortcut. The most common ones:190Press `?` in agent view to see every shortcut in context. The table below summarizes them.
154 191
155| Shortcut | Action |192| Shortcut | Action |
156| :-------------------- | :----------------------------------------------------------------------- |193| :-------------------- | :---------------------------------------------------------------------------------- |
157| `↑` / `↓` | Move between rows |194| `↑` / `↓` | Move between rows |
158| `Enter` | Attach to the selected session, or dispatch if there's text in the input |195| `Enter` | Attach to the selected session, or dispatch if there's text in the input |
159| `Space` | Open or close the peek panel for the selected session |196| `Space` | Open or close the peek panel for the selected session |
160| `Shift+Enter` | Dispatch and attach immediately |197| `Shift+Enter` | Dispatch and attach immediately |
161| `→` | Attach to the selected session |198| `→` | Attach to the selected session |
162| `Alt+1`..`Alt+9` | Attach to the Nth session in the focused group |199| `Alt+1`..`Alt+9` | Attach to session 1–9 in the current group |
163| `Tab` | Browse all subagents, or apply the highlighted suggestion |200| `Tab` | On an empty input, browse all subagents. Otherwise apply the highlighted suggestion |
164| `Ctrl+S` | Switch grouping between state and directory |201| `Ctrl+S` | Switch grouping between state and directory |
165| `Ctrl+T` | Pin or unpin the selected session |202| `Ctrl+T` | Pin or unpin the selected session |
166| `Ctrl+R` | Rename the selected session |203| `Ctrl+R` | Rename the selected session |
177 214
178### From agent view215### From agent view
179 216
180Type a prompt in the input at the bottom of agent view and press `Enter` to start a new background session. The session is named automatically from the prompt. You can rename it later with `Ctrl+R`. Paste an image into the prompt to include a screenshot or diagram with the task.217Type a prompt in the input at the bottom of agent view and press `Enter` to start a new background session. The session is named automatically from the prompt; rename it later with `Ctrl+R`.
218
219Paste an image into the prompt to include a screenshot or diagram with the task.
181 220
182Prefix or mention parts of the prompt to control how the session starts:221Prefix or mention parts of the prompt to control how the session starts:
183 222
190| `#<number>` or a pull request URL | If a session is already working on that PR, select it instead of dispatching |229| `#<number>` or a pull request URL | If a session is already working on that PR, select it instead of dispatching |
191| `Shift+Enter` | Dispatch and immediately attach to the new session |230| `Shift+Enter` | Dispatch and immediately attach to the new session |
192 231
193Type `/` to dispatch a [skill](/en/skills). Packaging a recurring task as a skill lets you start the same workflow many times from agent view without retyping the prompt. Press `Tab` on an empty input to browse every dispatchable subagent, or to apply the highlighted suggestion when suggestions are showing.232Packaging a recurring task as a [skill](/en/skills) lets you start the same workflow from agent view repeatedly without retyping the prompt.
194 233
195When the same `@name` matches both a subagent and a sibling repository, the subagent takes precedence. The first-word form without `@` also applies to any subagent name, so a prompt that begins with a word matching one of your subagent names dispatches that subagent. Use the `@` form when you want to be explicit.234When the same `@name` matches both a subagent and a sibling repository, the subagent takes precedence. The bare first-word match also applies, so a prompt that happens to begin with one of your subagent names dispatches that subagent rather than treating the word as plain text. Use the `@` form when you want to be explicit, or start the prompt with a different word to avoid the match.
196 235
197#### Dispatch to a specific directory236#### Dispatch to a specific directory
198 237
206 245
207### From inside a session246### From inside a session
208 247
209Run `/background` or its alias `/bg` to detach the current conversation and keep it running. Pass a prompt such as `/bg run the test suite and fix any failures` to send one more instruction before detaching.248Run `/background` or its alias `/bg` to move the current conversation into a background session. Pass a prompt such as `/bg run the test suite and fix any failures` to give one more instruction first.
249
250Backgrounding from an interactive session starts a fresh process that resumes from the saved conversation, so running subagents, [monitors](/en/tools-reference#monitor-tool), and background commands do not transfer to it. Claude asks you to confirm before backgrounding when any are running. Once in the background, the session can start new subagents, monitors, and background commands, and those keep running across later detach and reattach.
210 251
211### From the shell252### From your shell
212 253
213Pass `--bg` to start a session that goes straight to the background:254Pass `--bg` to start a session that goes straight to the background:
214 255
234 275
235### How file edits are isolated276### How file edits are isolated
236 277
237Every background session, whether started from agent view, `/bg`, or `claude --bg`, starts in your working directory but is blocked from writing files there. When the session needs to edit files, Claude moves it into an isolated [git worktree](/en/worktrees) under `.claude/worktrees/` automatically, so parallel sessions can read the same checkout but each writes to its own. The block doesn't apply when the session is already inside a worktree, when the working directory isn't a git repository, or to writes outside the working directory.278Every background session, whether started from agent view, `/bg`, or `claude --bg`, starts in your working directory. Before editing files, Claude moves the session into an isolated [git worktree](/en/worktrees) under `.claude/worktrees/`, so parallel sessions can read the same checkout but each writes to its own. Claude skips this when the session is already under `.claude/worktrees/`, when the working directory isn't a git repository, or for writes outside the working directory.
279
280Outside a git repository, sessions write to the working directory directly and aren't isolated from each other, so avoid dispatching parallel sessions that edit the same files.
238 281
239The worktree is removed when you delete the session, so merge or push the changes you want to keep before you delete. To find a session's worktree path, peek the session or attach and check its working directory.282The worktree is removed when you delete the session, so merge or push the changes you want to keep before you delete. To find a session's worktree path, peek the session or attach and check its working directory.
240 283
241To make a subagent always run in its own worktree regardless of how it was started, set [`isolation: worktree`](/en/sub-agents#supported-frontmatter-fields) in its frontmatter.284To make a subagent always run in its own worktree regardless of how it was started, set [`isolation: worktree`](/en/sub-agents#supported-frontmatter-fields) in its frontmatter.
242 285
286### Set the model
287
288The model name shown in the agent view header is the dispatch default. New sessions you start from the input use this model, which is the same setting [`/model`](/en/model-config) controls in any session.
289
290Each background session can run on a different model. To override it for one session:
291
292* From the shell, pass `--model` with `claude --bg`.
293* Attach to a running session and run `/model` there. The change persists if the session is respawned.
294* Dispatch a [subagent](/en/sub-agents) whose frontmatter sets a `model` field.
295
243### Permission mode and settings296### Permission mode and settings
244 297
245A dispatched session reads its [settings](/en/settings) and [permission mode](/en/permissions) from the directory it runs in, the same as if you had started `claude` there. Dispatching from the agent view input doesn't pass a permission mode, so the session uses the `defaultMode` from that directory's settings or the `permissionMode` from the dispatched [subagent's frontmatter](/en/sub-agents#supported-frontmatter-fields).298A dispatched session reads its [settings](/en/settings) and [permission mode](/en/permissions) from the directory it runs in, the same as if you had started `claude` there. Dispatching from the agent view input doesn't pass a permission mode, so the session uses the `defaultMode` from that directory's settings or the `permissionMode` from the dispatched [subagent's frontmatter](/en/sub-agents#supported-frontmatter-fields).
248 301
249## Manage sessions from the shell302## Manage sessions from the shell
250 303
251Every background session has a short ID you can use from the shell. These commands are useful for scripting or when you don't want to open agent view.304Every 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.
252 305
253| Command | Purpose |306| Command | Purpose |
254| :--------------------- | :----------------------------------------------------- |307| :--------------------- | :----------------------------------------------------------------------------------------- |
255| `claude agents` | Open agent view |308| `claude agents` | Open agent view |
256| `claude attach <id>` | Attach to a session in this terminal |309| `claude attach <id>` | Attach to a session in this terminal |
257| `claude logs <id>` | Print the session's recent output |310| `claude logs <id>` | Print the session's recent output |
258| `claude stop <id>` | Stop a session. Also accepts `claude kill` |311| `claude stop <id>` | Stop a session. Also accepts `claude kill` |
259| `claude respawn <id>` | Restart a stopped session with its conversation intact |312| `claude respawn <id>` | Restart a stopped session with its conversation intact |
260| `claude respawn --all` | Restart every stopped session |313| `claude respawn --all` | Restart every stopped session |
261| `claude rm <id>` | Remove a session from the list |314| `claude rm <id>` | Remove a session from the list. Cleans up its worktree if there are no uncommitted changes |
262 315
263## How background sessions are hosted316## How background sessions are hosted
264 317
265Background sessions are hosted by a per-user supervisor process, separate from your terminal and from agent view. It starts automatically the first time you background a session or open agent view, and you don't manage it directly. The supervisor and its sessions authenticate with the same credentials as your interactive sessions and make no additional network connections beyond the model API.318Every session listed in agent view is considered 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).
319
320### The supervisor process
321
322Background sessions are hosted by a per-user supervisor process, separate from your terminal and from agent view. The supervisor starts automatically the first time you background a session or open agent view, and you don't manage it directly.
323
324The supervisor and its sessions authenticate with the same credentials as your interactive sessions and make no additional network connections beyond the model API.
325
326Each background session is its own Claude Code process, managed by the supervisor rather than tied to your terminal. A session that's actively working, waiting for your input, or has a terminal attached keeps its process running.
266 327
267Each background session is its own Claude Code process, parented to the supervisor rather than to your terminal. A session that's actively working, waiting for your input, or has a terminal attached keeps its process running. Once a session finishes and sits unattached for about an hour, the supervisor stops its process to free resources. The transcript and state stay on disk, and the next time you attach, peek, or reply, the supervisor starts a fresh process from where it left off. When every session has finished and no terminal is connected, the supervisor itself exits and starts again the next time you background a session or open agent view.328Once a session finishes and sits unattached for about an hour, the supervisor stops its process to free resources. The transcript and state stay on disk, and the next time you attach, peek, or reply, the supervisor starts a fresh process from where it left off. When every session has finished and no terminal is connected, the supervisor itself exits and starts again the next time you need it.
268 329
269The supervisor watches the installed Claude Code binary on disk and restarts into the new version after the regular [auto-updater](/en/setup#auto-updates) replaces it. This is a local file watch, not a network check. Background sessions are detached processes, so they keep running through the restart and the new supervisor reconnects to them.330The supervisor watches the installed Claude Code binary on disk and restarts into the new version after the regular [auto-updater](/en/setup#auto-updates) replaces it. This is a local file watch, not a network check. Background sessions are detached processes, so they keep running through the restart and the new supervisor reconnects to them.
270 331
332### Where state is stored
333
271Session state is stored under your Claude Code config directory. If you set [`CLAUDE_CONFIG_DIR`](/en/env-vars), the supervisor uses that directory instead of `~/.claude` and runs as a separate instance with its own sessions.334Session state is stored under your Claude Code config directory. If you set [`CLAUDE_CONFIG_DIR`](/en/env-vars), the supervisor uses that directory instead of `~/.claude` and runs as a separate instance with its own sessions.
272 335
273| Path | Contents |336| Path | Contents |
276| `~/.claude/daemon/roster.json` | List of running background sessions, used to reconnect after a restart |339| `~/.claude/daemon/roster.json` | List of running background sessions, used to reconnect after a restart |
277| `~/.claude/jobs/<id>/state.json` | Per-session state shown in agent view |340| `~/.claude/jobs/<id>/state.json` | Per-session state shown in agent view |
278 341
342### Turn off agent view
343
279To turn off background agents and agent view entirely, set the `disableAgentView` [setting](/en/settings) to `true` or set the `CLAUDE_CODE_DISABLE_AGENT_VIEW` environment variable. Administrators can enforce this through [managed settings](/en/permissions#managed-settings).344To turn off background agents and agent view entirely, set the `disableAgentView` [setting](/en/settings) to `true` or set the `CLAUDE_CODE_DISABLE_AGENT_VIEW` environment variable. Administrators can enforce this through [managed settings](/en/permissions#managed-settings).
280 345
281## Troubleshooting346## Troubleshooting
282 347
348### `claude agents` lists subagents instead of opening agent view
349
350If `claude agents` prints a count followed by your configured subagents and then exits, agent view is unavailable in your environment. Earlier versions didn't open agent view in every environment, including when connected through Bedrock, Vertex AI, or Foundry. Run `claude update` to install the latest version.
351
352If agent view still does not open after updating, check whether it has been [turned off](#turn-off-agent-view) by a setting or environment variable.
353
283### Agent view opens with no sessions354### Agent view opens with no sessions
284 355
285Agent view is empty until you dispatch your first session. Type a prompt in the input at the bottom and press `Enter`.356Agent view is empty until you dispatch your first session. Type a prompt in the input at the bottom and press `Enter`.
286 357
287### Sessions show as stopped after waking your machine358### Cannot open agents because background tasks are running
359
360If pressing `←` to background the current session shows `Cannot open agents — N background task(s) running`, the session has in-flight work such as a subagent, a workflow, or a background shell command, and the shortcut won't silently abandon it. Run `/tasks` to see what's running, then `/bg` to confirm abandoning them. See [From inside a session](#from-inside-a-session) for what does and doesn't transfer when you background.
361
362### Prompt rejected as too short
363
364The dispatch input expects a task description, not a conversational opener. A prompt shorter than four characters is rejected with a `Too short` hint so a stray keystroke doesn't start a session. Describe what you want the session to do, such as `investigate the flaky checkout test`.
365
366### Sessions show as failed after waking your machine
288 367
289Background sessions don't survive sleep or shutdown. Attach, peek, or reply to any stopped session and it restarts from where it left off. To restart all of them at once, run `claude respawn --all`.368Background sessions don't survive sleep or shutdown, so sessions that were running show as failed after you wake. Attach, peek, or reply to any of them and the session restarts from where it left off. To restart all of them at once, run `claude respawn --all`.
290 369
291### A session is slow to respond after attaching370### A session is slow to respond after attaching
292 371
298 377
299## Limitations378## Limitations
300 379
301Agent view is a research preview. Current limitations to be aware of:380Agent view is in research preview with the following limitations:
302 381
303* **Rate limits apply**: background sessions consume your subscription usage the same as interactive sessions, so running ten agents in parallel uses quota roughly ten times as fast as running one.382* **Rate limits apply**: background sessions consume your subscription usage the same as interactive sessions, so running ten agents in parallel uses quota roughly ten times as fast as running one.
304* **Sessions are local**: background sessions run on your machine and stop if it sleeps or shuts down.383* **Sessions are local**: background sessions run on your machine and stop if it sleeps or shuts down.
305* **Worktrees are deleted with the session**: merge or push changes before deleting a session that edited files in its own worktree.384* **Worktrees are deleted with the session**: merge or push changes before deleting a session that edited files in its own worktree.
306 385
307## Next steps386## Related resources
308 387
309Now that you understand agent view, explore these related features:388For other ways to run Claude in parallel, see:
310 389
311* [Run agents in parallel](/en/agents): compare agent view with subagents, agent teams, and worktrees390* [Run agents in parallel](/en/agents): compare agent view with subagents, agent teams, and worktrees
312* [Subagents](/en/sub-agents): define reusable agent configurations with custom prompts, tools, and isolation
313* [Agent teams](/en/agent-teams): coordinate multiple sessions that message each other391* [Agent teams](/en/agent-teams): coordinate multiple sessions that message each other
314* [Claude Code on the web](/en/claude-code-on-the-web): run sessions in a managed cloud environment instead of locally392* [Claude Code on the web](/en/claude-code-on-the-web): run sessions in a managed cloud environment instead of locally
