Skip to main content
Agent 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. 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. Use 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. When you want to work more directly in any agent’s session, attach to the row to enter the full conversation. To compare agent view with subagents, agent teams, and worktrees, see Run agents in parallel.
Agent view is in research preview. The interface and keyboard shortcuts may change as the feature evolves.

​
Quick start

This 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.
1

Open agent view

From your shell, run:
If you haven’t yet accepted the workspace trust dialog for the directory, Claude Code shows it before agent view opens, the same dialog claude shows. Accept to save trust for the workspace and continue. If you decline, Claude Code exits without opening agent view.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; if you opened agent view by backgrounding a session with ←, Esc returns to that conversation instead. Your sessions keep running while you’re away and reappear the next time you open agent view.
2

Dispatch a session

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. Which permission mode it starts in depends on how you opened agent view.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.Each session uses your subscription quota independently, so see Limitations before dispatching many at once.
3

Peek and reply

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.
4

Attach and detach

Press Enter or → on a row to attach when you want the full conversation. The session takes over the terminal as a full interactive Claude Code session. Press ← on an empty prompt to detach and return to the table.
5

Bring an existing session in

This step needs a running session. If you followed the earlier steps you don’t have one open in this terminal, so open a regular claude session in another terminal and send it a message first.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. In a fresh session with no messages yet, /bg asks you to send a message first, while ← works right away. The session keeps running and appears as a row alongside the ones you dispatched.
You 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. Inside a regular claude session, the prompt footer’s ← hint counts the background agents that are waiting on you, such as ← 2 agents, and returns to ← for agents when none need input. Counts above 99 show as 99+. The count refreshes about every ten seconds while the terminal is focused and immediately when focus returns. It briefly changes color when it moves and when an agent completes, and when a background session finishes while none need your input it briefly shows the number completed, such as ← 2 done. Both flashes are off when the prefersReducedMotion setting is on, and the hint is hidden in screen reader mode.

​
Monitor sessions with agent view

Run 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 its age, counted from when the session was created; a finished session’s age freezes at how long the run took. The name is tinted with the color set by /color in that session, including when you background a session with ← or /background. By default the 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. To narrow the list to one project, pass --cwd:
This shows only sessions started under that directory. It still lists a session that has moved into a worktree under ~/projects/my-app/.claude/worktrees/. Interactive sessions you have open in other terminals don’t appear until you background them. Subagents and teammates a session spawns aren’t listed as separate rows.

​
Read session state

Each row starts with an icon whose color and animation show the session’s state: Separately, the icon’s shape shows whether the underlying process is running: The #N or !N label that can appear at the right edge of a row is a link to the session’s pull request or merge request, not part of the state icon. The 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. While agent view is open, Claude Code also sends a notification through your configured terminal notification channel when a local background session starts needing your input, finishes, or fails. Sessions that run on a schedule, such as /loop sessions, notify only when they need your input. Notifications use the same preferredNotifChannel setting as the rest of Claude Code and fire the Notification hook with the agent_needs_input or agent_completed type. Background sessions don’t need any terminal open to keep working. A separate 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. Session state persists on disk through auto-updates and supervisor restarts. Sessions are also preserved when your machine sleeps. Their processes resume on wake and the supervisor reconnects to them instead of treating the time gap as idle. Shutting down still stops running sessions; see Sessions show as failed after shutdown for how to recover them. A session that was mid-response when the machine slept can come back unresponsive. When you open a session that has stopped responding, the supervisor restarts its process and the session continues the interrupted response from where it left off.

​
Row summaries

The one-line summary in each row is generated by a Haiku-class model 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 row text updates at most once every 15 seconds from the session’s own recent output without sending a model request, and the model writes a fresh summary when each turn ends. A working row shows what the session says it’s doing, and a blocked row shows the question it’s asking. During a long turn, the model also rewrites the summary every few minutes so a busy row doesn’t keep showing an outdated one. The summary text fills the row’s remaining width; open the peek panel to read a sentence the terminal edge clips. When the list is grouped by directory, the summary opens with the session’s state as a colored word, such as Needs input · double jump or wall climb?. In the default state grouping, the group header already names the state, so the row shows only the summary. The end-of-turn summary and each mid-turn rewrite are one short Haiku-class request through your normal provider, billed and handled under the same data usage terms as the session itself. The 15-second updates between model rewrites reuse the session’s own output and don’t send a request. On a third-party provider or gateway with no Haiku-class model configured, the request uses the session’s main model instead; set ANTHROPIC_DEFAULT_HAIKU_MODEL to choose one.

​
Pull request status

When a session opens a pull request, Claude Code adds a label at the right edge of the row, linked to the pull request:
  • Claude Code writes the label as #1234 for a pull request and as !1234 for a GitLab merge request.
  • Claude Code emits the link even when it can’t detect hyperlink support, for example over SSH or tmux. Set FORCE_HYPERLINK=0 to render the label as plain text.
  • After you send a follow-up to the session, Claude Code keeps the label while the row returns to live progress.
A session that works on an existing pull request is linked to it the same way. Claude Code finds the pull request differently depending on the command Claude runs:
  • When Claude edits, comments on, closes, or marks a pull request ready with gh, Claude Code links the pull request that the command’s own output names. A gh command whose captured output names no pull request doesn’t create a link; gh pr merge is the common case, because it prints its result only to an interactive terminal.
  • When Claude checks a pull request out with gh pr checkout or pushes to a branch, Claude Code looks the branch up with gh pr view and links its open pull request.
  • The pull request doesn’t need to exist yet when Claude pushes: Claude Code retries the branch lookup after up to five later git, gh, glab, or curl commands run in the same directory, so a pull request created after the push, including one Claude creates through the GitHub REST API, links when a retry finds it.
When a session is linked to more than one pull request, the label shows a count instead, such as 3 PRs, colored by the open pull request that most needs attention. Open the peek panel to see them all. The pull request number is colored by its status: For a task that ends in a pull request, check this label for the result: review and merge the pull request when its number turns green.

​
Peek and reply

Press Space on a selected row to open the peek panel. It opens with the sentence the row truncates at the terminal edge, and which sentence that is depends on the session’s state:
  • A session that’s waiting on you: the exact question it’s asking, above the reply input
  • A finished session: its result
  • A working session: its full status sentence
Any pull requests linked to the session are listed next. For a session that’s waiting on you, a line such as waiting 3m below them shows how long it has been waiting, and it’s the only time shown in the panel. The age at the right edge of the row is a different number: it counts from when the session started. Most of the time the peek panel is enough and you don’t need to open the full transcript. Type a reply in the peek panel and press Enter to send it to that session. When the session asks a question with predefined choices, the peek panel shows them as a numbered list and you can press a number key to pick one. A permission prompt shows as text describing what the session wants to run, without numbered options. Type a reply to answer it, or attach to answer with the standard prompt. For other blocked sessions, press Tab to fill the input with a suggested reply you can edit before sending. Prefix a reply with ! to send a Bash command instead. A reply that can’t be delivered, because the background service is unreachable or the send fails, is saved and sent to the session as its next prompt when its process starts again, and the error message says the reply was saved. A reply prefixed with ! isn’t saved, because the saved text would reach the session as a plain prompt rather than run as a Bash command. With voice dictation enabled, hold or tap your push-to-talk key while the reply input is focused to dictate a reply instead of typing it. The same works in the dispatch input at the bottom of agent view. Use ↑ and ↓ to peek at adjacent sessions without closing the panel, or → to attach.

​
Attach to a session

Press Enter or → on a selected row to attach. Agent view is replaced by the full interactive session. When you attach, Claude posts a short recap of what happened while you were away. While attached, the session behaves like any other Claude Code session: commands, keyboard shortcuts, and features all work, with the exceptions below. While you’re attached, /install-github-app and the /mcp settings list work normally, since a human at the terminal can complete their dialogs. When nobody is attached, these commands can’t open their dialogs, so the session appears under Needs input in agent view with a row such as open this session to manage MCP servers, and the transcript reply says the same. Attach and run the command again to continue; the needs-input row clears when you attach. /mcp reconnect <server>, /mcp enable, and /mcp disable work without attaching either way. Attached sessions always render in fullscreen mode, regardless of your tui setting, because a background session has no terminal scrollback to append to. Scroll with PgUp, PgDn, or the mouse wheel, and press Ctrl+O for transcript mode. Your terminal’s native scroll and tmux copy mode show only the current viewport, the same as when you run any fullscreen application. Press ← 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. On 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. 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 ←. Ctrl+C keeps its standard interrupt behavior while attached: it cancels a running response or ! shell command rather than detaching. Pressing Ctrl+C twice on an empty prompt detaches, the same as in any session. Detaching never stops a background session: ←, Ctrl+Z, /exit, and double Ctrl+C or double Ctrl+D all leave it running. To end a session from inside it, run /stop.

​
Switch sessions without leaving the terminal

In a session running in the foreground, one you started in the terminal rather than attached to from agent view, pressing ← on an empty prompt backgrounds it and opens agent view with that row selected, so you can switch sessions without leaving the terminal. The same single press detaches an attached session. If you press ← right after you delete the last of the prompt’s text or move through prompt history, Claude Code asks you to confirm: the first press shows Press ← again to open agents, or Press ← again to go back to agents in an attached session, and the second press switches. When ← backgrounds a foreground session, agent view shows Your conversation moved to the background above the list, with that session’s row already selected. From there:
  • Press Enter to reopen the conversation.
  • Press Esc to undo the switch and return to the conversation. If Esc shows Still starting — try again in a moment, the background session isn’t ready yet, so press Esc again in a moment.
  • Press Ctrl+C twice to exit to your shell.
When Claude Code can’t reopen the conversation, it exits and prints a claude --resume command that resumes it. Claude’s task list moves to the background session with the conversation, so the checklist is intact when you return to that row. The row you pressed ← from also keeps a bold, undimmed name after you move the selection with the arrow keys or the mouse, so you can tell which session you came from. If a tool is running when you press ←, Claude Code waits up to about ten seconds for it to finish before backgrounding, and the response continues in the background session. Press ← again to background immediately instead of waiting. When in-flight work can’t carry over to the background session, the Background this session? dialog appears first, the same as with /background. The ten-second limit doesn’t apply while subagents are running. Claude Code keeps waiting so their work carries over, and shows a Still backgrounding after the current tool notice while it waits; press ← again to background without waiting, which restarts the subagents from the beginning. Claude Code doesn’t background the session while you have unsent text in the prompt input, because the text stays in your terminal’s input box and wouldn’t move to the background session. If you type into the input while Claude Code waits to background the session, it cancels the switch with Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again. Pressing ← creates the session’s row even when the conversation has no messages yet, so → still returns to it. You can turn this shortcut off with the leftArrowOpensAgents setting in /config.

​
Organize the list

Agent 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 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. Within a group:
  • Press Ctrl+T to pin a session to the top and keep its process running while idle
  • Press Shift+↑ or Shift+↓ to reorder sessions
  • Press Ctrl+R to rename a session
  • Press Enter on a group header to collapse it
To 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. The second press deletes the session even when the stop attempt fails, for example because the background service isn’t responding: the confirmation stays active for another two seconds, and the delete ends the session’s process itself. Press Esc to dismiss the confirmation without deleting. Except in the kept cases covered in What deleting a session removes, deleting removes the session from the list, and a worktree Claude created for it is removed, kept, or left in place depending on how you delete and what the worktree holds. The conversation transcript always stays on your local machine, available through claude --resume. To bring a session back on Claude Code v2.1.212 or later, type /resume in the dispatch input. A picker opens with past sessions of the repository you opened agent view from, newest first, including sessions you deleted from the list; sessions that already have a row aren’t listed. ↑/↓ move the selection, Enter resumes the selected session as a background session so it rejoins the list as a row, and Esc closes the picker. The picker opens only for a bare /resume. A targeted, scoped, or restricted resume can’t be served by the picker, so agent view shows the attach to a session to run it hint instead when:
  • /resume names an id or a search term
  • the view is scoped with --cwd
  • the view was started with --safe-mode
  • the view was opened with a flag such as --permission-mode or --settings
Completed sessions that don’t fit on screen fold into a … N more row. Failures and sessions with an open pull request always stay visible. The Completed group fills the vertical space left after the live groups, and on a short terminal the header compacts to a single summary line so sessions that are working or need input stay visible.

​
Filter sessions

Type in the dispatch input to filter instead of dispatching:

​
Keyboard shortcuts

Press ? in agent view to see every shortcut in context. The table below summarizes them.

​
Dispatch new agents

You 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 agent view

Type 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. The automatic name is a short label written by a Haiku-class model. A name the session gets later also appears on its row, including the name Claude derives when you accept a plan in that session. Paste an image into the prompt to include a screenshot or diagram with the task. Pasted text longer than 800 characters or more than two lines collapses to a [Pasted text #N] placeholder so the input stays on one line; the full text is sent when you dispatch. To review or edit the collapsed text before dispatching, paste the same text again and the placeholder expands back into the input. Prefix or mention parts of the prompt to control how the session starts: A small set of commands run in agent view itself instead of dispatching:
  • /exit and /quit close agent view
  • /logout signs you out
  • /model sets the dispatch model
  • /login opens the sign-in dialog so you can sign in again without attaching to a session
  • A bare /resume, or its /continue alias, opens a picker of the repository’s past sessions to bring one back as a background session. Requires Claude Code v2.1.212 or later
Skills, your own commands, and prompt-expanding built-ins such as /init are sent to a new background session as their first prompt. Other built-in commands show an attach to a session to run it hint instead. Everything you typed stays in the input next to the hint so you can edit it. Packaging a recurring task as a skill lets you start the same workflow from agent view repeatedly without retyping the prompt. When 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.

​
Dispatch to a specific directory

A new session runs in the directory you opened agent view from. To target a different directory, use any of these:
  • Open claude agents in that directory.
  • Open claude agents in a parent directory and mention a child repository with @<repo> in the prompt. Typing @ lists these targets:
    • Git repositories one level below the launch directory
    • The registered git worktrees of the repository you launched from that live inside its directory tree, such as the ones Claude creates under .claude/worktrees/, labeled with their checked-out branch. Worktrees added outside the repository, such as with git worktree add ../feature, aren’t listed
    • Any directory that already has a session in the list
    A directory whose name contains a space isn’t listed.
  • From the shell, cd into the directory and run claude --bg "<prompt>".
When agent view is grouped by directory, dispatching sends the prompt to the selected row’s directory, so you can select a group and dispatch into it without retyping the path.

​
From inside a session

Two commands move work from the session you’re in to the background: /background sends the current conversation there and frees your terminal, and /fork sends a copy while you keep working where you are.

​
Send the session to the background

Run /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. If Claude is responding when you run /bg, the response continues in the background session. Exiting a session that still has background work running, such as subagents, background shell commands, workflows, or monitors, shows a Background work is running dialog instead of quitting immediately. Choose Move to background and exit to background the session the same way /background does and return to your shell. The option isn’t shown when agent view is turned off.

​
Copy the session with /fork

Run /fork to copy the current conversation into a new background session while the original keeps running. The copy starts with everything in the conversation up to that point; see the bullets below for where the copy runs. It also carries over the model, permission mode, effort level, and any directories or “don’t ask again” permission grants you added during the session. The copy appears as its own row in agent view. After the fork, the two conversations are independent: nothing the copy does enters the original conversation on its own, though in sessions where cross-session messaging is enabled, either session’s Claude can explicitly message the other. Copying the session requires Claude Code v2.1.212 or later; on v2.1.161 through v2.1.211, /fork starts a forked subagent instead, which is now /subtask. When agent view is turned off, /fork keeps the forked-subagent behavior and /subtask isn’t available. Pass a prompt such as /fork open a draft pull request with the work so far and the copy starts working on it immediately. Without a prompt the copy waits for its first instruction: select its row in claude agents and press Space to send one, or run claude attach <id>. The selected row shows space to send it a prompt while it waits. The /fork confirmation is one line showing the copy’s state, such as session running, the name of its agent-view row, and its session ID for claude attach. Click the name to switch into the copy: this session moves to the background, the same as pressing ←, and agent view opens the copy’s session. Except when the copy edits in place, Claude Code instructs it to create a worktree of its own before making code changes. Outside a git repository, only a copy moved out of a hook-created worktree gets the instruction; with no WorktreeCreate hook, the copy edits in place. A copy moved out of your worktree is also told never to edit, run commands in, or enter that worktree, whatever the isolation setting. Where the copy starts depends on where the current session is running:
  • Like any dispatched session, the copy moves into its own worktree before editing files. In that case the confirmation doesn’t mention where the copy runs.
  • When your session moved into its linked worktree after it started, the copy starts back where the session was before the move and, unless it edits in place, makes its code changes in a worktree of its own there. When your worktree is checked out on a branch, that instruction also tells a copy whose task builds on your work to base its new branch on yours, since your branch stays checked out in your worktree. The confirmation ends with runs in the origin tree.