Agent View: claude agents
Agent view, opened with claude agents, is a single dashboard for every background Claude Code session on your machine. Each row is a full conversation that keeps running without a terminal attached. You dispatch new sessions from the input at the bottom, peek at any row to see its last output, attach for the full transcript, and step in only when one needs you.
It debuted on May 11, 2026 alongside Claude Code v2.1.139 as a research preview on Pro, Max, Team, Enterprise, and Claude API plans. Verify your version with claude --version before relying on it.
Quick Start
Section titled “Quick Start”-
Open agent view. From your shell:
Terminal window claude agentsThe view takes over the terminal. Press
Escat any time to return to your shell — sessions keep running and reappear next time you open the view. -
Dispatch a session. Type a task in the input at the bottom and press
Enter. A new background session starts and shows up as a row indicating whether it’s working, waiting on you, or done. Every prompt creates its own new session, so typing two prompts launches two parallel sessions. -
Peek and reply. Select a row with the arrow keys and press
Spaceto open the peek panel — most recent output, or the question the session is blocked on. Type a reply and pressEnterto send it without leaving agent view. -
Attach and detach. Press
Enteror→on a row to attach to the full conversation. Press←on an empty prompt to detach back to the table. Detaching never stops a background session. -
Bring an existing session in. Inside any open session, run
/bgto background it, or press←on an empty prompt to background and open agent view in one step.
You can use claude agents as your main entry point instead of claude: dispatch everything from the dashboard, attach when you want the full transcript, press ← to come back.
Read Session State
Section titled “Read Session State”Each row starts with an icon whose color shows the session state and shape shows whether the underlying process is alive.
State (color)
Section titled “State (color)”| State | Icon | Meaning |
|---|---|---|
| Working | Animated | Claude is actively running tools or generating a response |
| Needs input | Yellow | Claude is waiting on a question or permission decision from you |
| Idle | Dimmed | Nothing to do; ready for your next prompt |
| Completed | Green | The task finished successfully |
| Failed | Red | The task ended with an error |
| Stopped | Grey | Stopped with Ctrl+X or claude stop |
Process (shape)
Section titled “Process (shape)”| Shape | Meaning |
|---|---|
✻ / ✽ | Session process is alive; replies immediately |
∙ | Process has exited; peek/reply/attach still work and restart from where it left off |
✢ | A /loop session sleeping between iterations. Row shows run count and countdown |
Background sessions don’t need any terminal open. A separate supervisor process runs them, so you can close agent view, close your shell, or start a new interactive session and the dispatched work keeps going.
Pull Request Status
Section titled “Pull Request Status”When a session opens a pull request, a status dot appears at the right edge of the row, linked to the PR in terminals that support hyperlinks.
| Dot color | Pull request status |
|---|---|
| Yellow | Waiting on checks or review, or checks failed |
| Green | Checks passed and no review is blocking |
| Purple | Merged |
| Grey | Draft or closed |
For most autonomous tasks this row is the entire interface — review and merge the PR when the dot turns green.
Peek and Reply Without Attaching
Section titled “Peek and Reply Without Attaching”Press Space on a selected row to open the peek panel. It shows the session’s most recent output, any blocking question, and any open pull requests.
Type in the peek panel and press Enter to send a reply. When the session asks a multiple-choice question, press a number key to pick. For other blocked sessions, press Tab to fill the input with a suggested reply you can edit. Prefix a reply with ! to send a Bash command instead.
Use ↑ and ↓ to peek at adjacent sessions without closing the panel; → attaches.
Attach to a Session
Section titled “Attach to a Session”Press Enter or → on a row to attach. Agent view is replaced by the full interactive session, exactly as if you had run claude in that directory. Claude posts a short recap of what happened while you were away.
While attached, the session behaves like any other Claude Code session — every command, shortcut, and feature works. Press ← on an empty prompt to detach. If a dialog has focus and isn’t responding to ←, press Ctrl+Z to detach immediately.
←, Ctrl+C, Ctrl+D, Ctrl+Z, and /exit all leave the background session running. To end a session from inside it, run /stop. You can disable the ← shortcut in /config if you keep hitting it accidentally.
Organize and Filter
Section titled “Organize and Filter”Agent view groups sessions so the ones that need input are at the top — Ready for review and Needs input above Working and Completed. Press Ctrl+S to switch grouping to by-directory and back. Your choice persists across runs.
Within a group:
Ctrl+T— pin a session to the topShift+↑/Shift+↓— reorder sessionsCtrl+R— rename a sessionEnteron a group header — collapse itCtrl+X— stop a session; press again within 2 seconds to delete it (including its worktree)
Type in the dispatch input to filter the list instead of dispatching:
| Filter | Shows |
|---|---|
a:<name> | Sessions running the named agent |
s:<state> | Sessions in the given state, e.g. s:working, s:blocked |
#<number> or PR URL | The session working on that pull request |
Keyboard Shortcuts
Section titled “Keyboard Shortcuts”Press ? in agent view to see every shortcut in context.
| Shortcut | Action |
|---|---|
↑ / ↓ | Move between rows |
Enter | Attach to selected session, or dispatch if there’s text in the input |
Space | Open / close the peek panel |
Shift+Enter | Dispatch and attach immediately |
→ | Attach to the selected session |
Alt+1..Alt+9 | Attach to session 1–9 in the current group |
Tab | On an empty input: browse all subagents. Otherwise: apply highlighted suggestion |
Ctrl+S | Switch grouping between state and directory |
Ctrl+T | Pin or unpin the selected session |
Ctrl+R | Rename the selected session |
Ctrl+G | Open the dispatch prompt in $EDITOR |
Ctrl+X | Stop the session; press again within 2 seconds to delete it |
Shift+↑ / Shift+↓ | Reorder the selected session |
Esc | Close peek panel, clear input, or exit |
Ctrl+C | Clear input; press twice to exit |
? | Show all shortcuts |
Dispatch New Agents
Section titled “Dispatch New Agents”Three places to start a background session:
From agent view
Section titled “From agent view”Type a prompt in the input and press Enter. The session is named automatically from the prompt; rename it later with Ctrl+R. Paste an image into the prompt to include a screenshot or diagram.
| Input | Effect |
|---|---|
<agent-name> <prompt> | If the first word matches a subagent name, that subagent runs as main agent |
@<agent-name> | Mention a subagent anywhere in the prompt to run it as main agent |
@<repo> | Mention a sibling repo to run the session there |
/<skill> | Suggest skills to dispatch as the prompt |
#<number> or PR URL | If a session is already working on that PR, select it instead of dispatching |
Shift+Enter | Dispatch and immediately attach |
From inside a session
Section titled “From inside a session”/bgMove the current conversation into a background session. Pass a final instruction in the same line — /bg run the test suite and fix any failures. Backgrounding starts a fresh process that resumes from the saved conversation; Claude asks for confirmation if subagents or background commands are still running.
From your shell
Section titled “From your shell”claude --bg "investigate the flaky SettingsChangeDetector test"To run a specific subagent as the session’s main agent:
claude --agent code-reviewer --bg "address review comments on PR 1234"After backgrounding, Claude prints the session’s short ID and the commands for managing it.
Manage Sessions from the Shell
Section titled “Manage Sessions from the Shell”Every background session has a short ID (printed by claude --bg, also the directory name under ~/.claude/jobs/).
| Command | Purpose |
|---|---|
claude agents | Open agent view |
claude attach <id> | Attach to a session in this terminal |
claude logs <id> | Print the session’s recent output |
claude stop <id> | Stop a session. Also accepts claude kill |
claude respawn <id> | Restart a stopped session with its conversation intact |
claude respawn --all | Restart every stopped session |
claude rm <id> | Remove a session. Cleans up its worktree if there are no uncommitted changes |
These are how you script agent view — for example, a cron job that respawns sessions after the laptop wakes from sleep.
How File Edits Are Isolated
Section titled “How File Edits Are Isolated”Every background session — agent view, /bg, or claude --bg — starts in your working directory. Before editing files, Claude moves the session into an isolated git worktree under .claude/worktrees/, so parallel sessions read the same checkout but each writes to its own. Outside a git repository, sessions write directly and aren’t isolated from each other.
The worktree is removed when you delete the session, so merge or push the changes you want to keep before deleting. To make a subagent always run in its own worktree regardless of how it was started:
---name: code-reviewerisolation: worktree---Permission Mode and Settings
Section titled “Permission Mode and Settings”A dispatched session reads its settings and permission mode from the directory it runs in — the same as claude started there. To override from the shell:
claude --bg --permission-mode plan "draft the implementation plan for the new pricing page"Using bypassPermissions or auto this way is refused until you’ve accepted that mode by running claude with it once interactively, since those modes let a session you aren’t watching act without approval.
The Supervisor Process
Section titled “The Supervisor Process”Background 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; you don’t manage it directly.
A session that’s working, waiting for 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; the next time you peek, reply, or attach, the supervisor starts a fresh process from where it left off.
The supervisor watches the installed Claude Code binary on disk and restarts into the new version after the auto-updater replaces it. Background sessions are detached processes — they keep running through the restart.
State storage
Section titled “State storage”If you set CLAUDE_CONFIG_DIR, the supervisor uses that instead of ~/.claude and runs as a separate instance.
| Path | Contents |
|---|---|
~/.claude/daemon.log | Supervisor log |
~/.claude/daemon/roster.json | List of running sessions (used to reconnect after restart) |
~/.claude/jobs/<id>/state.json | Per-session state shown in agent view |
Disable agent view
Section titled “Disable agent view”To turn off background agents and agent view entirely:
{ "disableAgentView": true }Or set CLAUDE_CODE_DISABLE_AGENT_VIEW=1. Admins can enforce this through managed settings.
Troubleshooting
Section titled “Troubleshooting”claude agents lists subagents instead of opening the view
Section titled “claude agents lists subagents instead of opening the view”Earlier versions didn’t open agent view in every environment (Bedrock, Vertex AI, Foundry). Run claude update to install the latest version. If it still doesn’t open, check whether it’s been disabled by a setting or env var.
”Cannot open agents — N background task(s) running”
Section titled “”Cannot open agents — N background task(s) running””The session you’re trying to background has in-flight work — a subagent, a workflow, or a background shell command. Run /tasks to see what’s running, then /bg to confirm abandoning them.
Prompt rejected as too short
Section titled “Prompt rejected as too short”The dispatch input expects a task description, not a one-word query. Prompts under four characters are rejected with Too short.
Sessions show as failed after waking your machine
Section titled “Sessions show as failed after waking your machine”Background sessions don’t survive sleep or shutdown. Attach, peek, or reply to any of them and they restart from where they left off — or claude respawn --all to restart them all at once.
.claude/worktrees/ is filling up
Section titled “.claude/worktrees/ is filling up”Worktrees are removed when you delete the session that created them. If a session ended without cleaning up, list leftovers with git worktree list in the project directory and remove each with git worktree remove <path>.
Limitations (Research Preview)
Section titled “Limitations (Research Preview)”- Rate limits apply. Background sessions consume your subscription usage the same as interactive ones — ten parallel agents burn quota roughly ten times as fast.
- Sessions are local. They run on your machine and stop if it sleeps or shuts down.
- Worktrees die with the session. Merge or push changes before deleting a session that edited files.