# 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](https://code.claude.com/docs/en/agents) 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]]