Claude Code Agent View

Canonical version: Claude Code Agent View.

Agent view, opened with claude agents, is one screen for dispatching and managing many background Claude Code sessions. Each row shows what a session is doing, what it needs, or what it produced — without scrolling through transcripts. Requires v2.1.139+; in research preview, so the UI and shortcuts may change.

Background sessions are full Claude Code conversations hosted by a per-user supervisor process, so they keep running with no terminal attached. Close agent view, close the shell, or reboot the laptop — sessions stop only on sleep/shutdown and can be revived with claude respawn --all.

Why it matters

Replaces the "many terminals, many tmux panes, many half-forgotten sessions" pattern with one inbox-style view. Dispatch a bug fix, a PR review, and a flaky-test investigation as three rows; check back when one says it needs input or has a result.

Quick start

• claude agents — opens the view. Esc to leave; sessions keep running
• Type a prompt + Enter — dispatches a new background session as a new row
• Space on a row — peek panel (last output or pending question); type a reply and Enter to send
• Enter / → on a row — attach (full interactive session, as if you had run claude)
• ← on an empty prompt — detach back to the table (also works from any session to background it)
• /bg inside a running session — sends it to the background and into agent view

Session states

Icon color/animation shows state; icon shape shows whether the process is alive.

• Working (animated), Needs input (yellow), Idle (dimmed), Completed (green), Failed (red), Stopped (grey)
• ✻ / animated ✽ — process alive; ∙ — process exited (still resumable); ✢ — /loop session sleeping between iterations
• After ~1h idle with no terminal attached, the supervisor kills the process. Peek/attach restarts it from where it left off.

Pull-request status

When a session opens a PR, a coloured dot appears on the right (yellow = waiting/failed checks, green = passed, purple = merged, grey = draft/closed). For most tasks this row is where the work gets picked up: dispatch → green dot → review → merge.

Dispatch patterns

• <agent-name> <prompt> or @<agent-name> — runs that custom subagent as the session's main agent
• @<repo> — runs the session in a sibling repo under the directory agent view was opened from
• /<skill> — suggests skills to dispatch as the prompt (recurring tasks → package as a skill)
• #<number> or a PR URL — selects the existing session for that PR instead of starting a new one
• Shift+Enter — dispatch and immediately attach
• Ctrl+G — open the prompt in $EDITOR for long inputs
• Filter the list (no dispatch) with a:<name>, s:<state> (incl. s:blocked), or #<number> / PR URL

Worktree isolation

Before editing files, a background session moves itself into an isolated Git Worktree under .claude/worktrees/. Parallel sessions read the same checkout but each writes to its own. Merge or push before deleting the session — the worktree is removed with it. Outside a git repo, no isolation: avoid parallel edits to the same files.

Defaults that travel

Flags passed to claude agents apply to itself and every session it dispatches:

• --permission-mode <mode> — bypassPermissions / auto require having accepted them once interactively first (since a session you aren't watching would act without approval)
• --model <name>, --effort <level>
• --settings, --add-dir, --plugin-dir, --mcp-config, --strict-mcp-config
• --cwd <path> scopes the view to one project (incl. its worktrees)

Shell management

Every session has a short ID, printed when started via claude --bg "<prompt>" (combine with --agent <name> and --name <display>).

• claude attach <id> — open in this terminal
• claude logs <id> — recent output
• claude stop <id> / claude kill <id>
• claude respawn <id> / claude respawn --all
• claude rm <id> — remove from list (cleans worktree if no uncommitted changes)

Limitations

• Local-only — sessions run on your machine, stop on sleep/shutdown
• Quota — each session consumes subscription usage independently; 10 in parallel ≈ 10× the burn rate
• Worktree destruction on delete — push/merge first
• No nested sessions — subagents and teammates a session spawns don't appear as rows
• Disable entirely via disableAgentView setting or CLAUDE_CODE_DISABLE_AGENT_VIEW

How it differs from siblings

• vs AI Subagents: subagents run inside one session and only report back; agent view sessions are independent processes with their own conversation
• vs Claude Code Agent Teams: teams coordinate via shared mailbox + task list and can message each other; agent view sessions are siblings, not collaborators
• vs Claude Code Web: web runs sessions in Anthropic's cloud and survives your machine sleeping; agent view runs locally
• See Run agents in parallel for the full comparison

References

• Agent view: https://code.claude.com/docs/en/agent-view
• Run agents in parallel: https://code.claude.com/docs/en/agents

Related

• Claude Code
• Claude Code Tasks
• Claude Code Agent Teams
• Claude Code Web
• Claude Code Skills
• AI Subagents
• AI Agents

About Sébastien

Ready to get to the next level?