Agent View Session Management#
Agent View is a terminal dashboard that shows every Claude Code session in a single list — running, waiting on input, or done. Run claude agents to open it. It was introduced as a Research Preview in v2.1.139 and is the primary interface for dispatching and supervising background sessions.
Official docs: code.claude.com/docs/en/agent-view
Key things Agent View handles:
- Dispatching new background sessions from one screen
- Monitoring status across all sessions (working, blocked, completed, failed)
- Pinning, renaming, reordering, and stopping sessions
- JSON output for scripting and automation
Session States and the Dashboard#
Each row in Agent View shows a session's status, its last action summary, elapsed time, and — when applicable — pull request status.
States:
| State | Indicator | Meaning |
|---|---|---|
| Working | Animated icon | Claude is actively running tools or generating a response |
| Needs input | Yellow | Waiting on a question or permission decision |
| Idle | Dimmed | Ready for the next prompt |
| Completed | Green | Task finished successfully |
| Failed | Red | Task ended with an error |
| Stopped | Grey | Manually stopped with Ctrl+X or claude stop |
Row icons:
✻/ animated✽— session process is alive and replies immediately∙— process has exited; attaching or replying restarts it from where it left off✢— a/loopsession sleeping between iterations
Since v2.1.145, the terminal tab title shows the count of sessions awaiting input, so you can see at a glance when attention is needed from another window.
Organizing sessions:
Ctrl+S— toggle grouping between state-based and directory-based viewsShift+↑/Shift+↓— manually reorder sessions within a group- Filter syntax:
a:<name>(by agent),s:<state>(e.g.s:blocked),#<number>or a PR URL (by pull request)
Pinning and Renaming Sessions#
Pinning (Ctrl+T): Introduced in v2.1.147. Pinned sessions stay alive when idle (non-pinned sessions can be reaped by the supervisor). They are restarted in place when Claude Code updates, and are only shed under memory pressure after all non-pinned sessions. Use pinning for long-running or high-priority sessions you want to keep warm.
Renaming (Ctrl+R): Added in v2.1.144. Renaming a background session updates the attached session's banner immediately. You can also set a name at dispatch time with claude --bg --name <label> — the name is echoed in the post-spawn confirmation. Names appear in claude agents --json output as the name field.
CLI Flag Configuration#
Flags passed to claude agents apply to the dashboard itself and to every background session dispatched from it. Added in v2.1.142–2.1.143.
(Full reference in official docs)
| Flag | Effect |
|---|---|
--model <model> | Default model for dispatched sessions |
--effort <level> | Default effort level (low, medium, high) |
--permission-mode <mode> | Default permission mode (e.g. plan, auto, bypassPermissions) |
--settings <file-or-json> | Override settings for agent view and dispatched sessions |
--add-dir <path> | Grant file access to an additional directory |
--mcp-config <file-or-json> | Load MCP servers from a config file or JSON string |
--plugin-dir <path> | Load a plugin from a local directory |
--dangerously-skip-permissions | Skip permission prompts (persists across retire→wake) |
--cwd <path> | Scope the session list to sessions started under <path> |
Example:
claude agents --permission-mode plan --model opus --effort high
claude agents --settings ./ci-settings.json --add-dir ../shared-lib
--cwd is useful in monorepos to focus on sessions for a specific project directory. Added in v2.1.141.
Shell Commands for Session Management#
Beyond the interactive UI, sessions can be managed from any shell. (Full reference)
| Command | Purpose |
|---|---|
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: claude kill) |
claude respawn <id> | Restart a session (running or stopped) with conversation intact — useful for picking up a new binary |
claude respawn --all | Restart every running session at once |
claude rm <id> | Remove a session; cleans up any Claude-created worktree if it has no uncommitted changes |
claude daemon status | Show supervisor state, version, socket directory, and worker count |
Sessions move to Completed once the task finishes, even if a background shell remains open — fixed in v2.1.141. Transcripts persist locally and remain available via claude --resume even after a session is removed from Agent View.
JSON Export for Automation#
claude agents --json prints the list of live Claude Code sessions as a JSON array and exits. Added in v2.1.145.
Each entry contains:
| Field | Present when |
|---|---|
pid | Always |
cwd | Always |
kind | Always |
startedAt | Always |
sessionId | Set |
name | Named (via --name or Ctrl+R) |
status | Set |
Combine with --cwd <path> to filter by directory:
claude agents --json --cwd ~/projects/my-app
Primary use cases cited at launch: tmux-resurrect integrations, custom status bars, and session pickers .
State Storage and Architecture#
Agent View is backed by a supervisor daemon process that hosts background sessions. (Architecture reference)
Key paths (relative to CLAUDE_CONFIG_DIR, default ~/.claude):
| Path | Contents |
|---|---|
~/.claude/daemon.log | Supervisor log |
~/.claude/daemon/roster.json | List of running sessions — used to reconnect after a restart |
~/.claude/jobs/<id>/state.json | Per-session state shown in Agent View rows |
Background sessions created via /bg or claude --bg get git worktree isolation by default under .claude/worktrees/. Set worktree.bgIsolation: "none" in settings.json to disable this and have sessions edit the working copy directly.
Disabling Agent View: set disableAgentView: true in settings or CLAUDE_CODE_DISABLE_AGENT_VIEW=1 in the environment.
