[FEATURE] Agent Hierarchy Dashboard — unified real-time visualization for multi-agent workflows (TUI + Desktop) #24537

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

When Claude Code dispatches complex workloads with nested Task agents, there is some ability to view context and task but it is displayed in a sub-optimal way (i.e. it's not a great experience having the work being performed by agents in the same terminal window as the session. The conversation view interleaves tool calls from the main agent with subagent results, but you cannot see the following without obfuscating the current terminal session or at all (that I am aware of):

• How many agents are running and what each is doing right now
• Per-agent resource usage — which agent is consuming context, tokens, and cost
• The agent tree — which agent spawned which, and their parent-child relationships
• Task progress per agent — not just the top-level task list, but what each agent is working on
• Historical replay — what happened during a complex multi-agent run

This problem/opportunity exists in both the CLI and Desktop Code mode as I believe they share the same agent/subagent engine.

Rationale

The Claude Code conversation view was designed for a human talking to one agent. It was never meant to be a control plane for 7 concurrent subagents across multiple sessions. Cramming agent trees, resource metrics, task progress, and approval prompts into an interleaved chat transcript is what creates the overload.

The answer is separation, not subtraction.

This proposal moves operational complexity out of the conversation view and into a dedicated dashboard surface (TUI overlay / Desktop sidebar):

• Agent tree, per-agent metrics, and task progress get a purpose-built interface instead of cluttering chat scroll
• Approval prompts surface in a dedicated activity stream instead of getting buried
• Session switching and cost tracking live in a control plane, not inline text output
• The conversation view goes back to what it does best: focused dialogue with the primary agent

This is a proven pattern:

• Kubernetes moved monitoring into dashboards (k9s, Lens) — kubectl stayed focused on direct interaction
• VS Code put debugging, git, and terminals in collapsible panels — the editor stays clean
• tmux layered a control plane on top of shell sessions — keeping the two concerns separate

You can simplify the conversation view not by removing features from the product, but by giving them a better home. The 20+ issues this proposal consolidates aren't asking for fewer features. They're asking for the right features in the right place.

This Proposal Unifies 20+ Existing Issues

The community has filed many fragmented requests that all point at the same gap. This proposal provides the product design that makes infrastructure investments in agent observability worthwhile.

Agent Monitoring / Identification:

• SubagentStop hook cannot identify which specific subagent finished due to shared session IDs #7881 — SubagentStop hook cannot identify which specific subagent finished (19 upvotes)
• [FEATURE] 1. Agent Hierarchy in Hook Events, 2. Intermediate Text Output Hook, 3. SubagentStart Hook #14859 — Agent Hierarchy in Hook Events + SubagentStart Hook (9 upvotes)
• [FEATURE] Expose Agent Context in Hook Event Payloads for Multi-Agent Observability #16424 — Expose Agent Context in Hook Event Payloads for Multi-Agent Observability (7 upvotes)
• Feature Request: Expose current agent information for external monitoring #10052 — Expose current agent information for external monitoring
• [FEATURE] Event Subscriptions for Real-Time Agent Communication #20921 — Event Subscriptions for Real-Time Agent Communication
• [FEATURE] Show sub-agent token usage in /context command and Task tool output #10164 — Show sub-agent token usage in /context command
• [FEATURE] Agent Token Usage API - Critical Infrastructure for Agent Development Ecosystem #10388 — (Related agent monitoring)
• Feature: Show model name in tool call UI for subagents/Task tool #24094 — Show model name in tool call UI for subagents

Per-Agent Resource Tracking:

• [FEATURE] Per-Subagent Token Usage Tracking #22625 — Per-Subagent Token Usage Tracking
• Feature Request: Usage Limit Visibility and Threshold Alerts #17431, Feature Request: Unified usage stats across machines and Claude interfaces #15434, [FEATURE] Automatic Cost Tracking and Reporting #18550 — Cost/usage visibility

Session Management:

• [FEATURE] Add /list-sessions and /delete-session slash commands for better session management #16901, m #2562, [FEATURE] Add centralized session/token management dashboard for Claude Code Max subscribers #22995, [FEATURE] Visual project-based session organization with folders and pinning #22617, Feature Request: Renamable/Named Sessions in Claude Code Extension #17536, [FEATURE] Project-Local Conversation History Storage #9306 — Session management improvements

Multi-Session:

• [Feature Request] Expose Session Metadata via Environment Variables and API #17188, [Feature Request] Per-Session Workspace Isolation - Critical for Multi-Session Workflows #16311, [Feature Request] Cross-repository session communication for multi-repo workflows #20559, Feature Request: Session Linking - Allow new sessions to reference previous conversation context #18401, [FEATURE] Resumable Subagent Sessions (Persistent Multi-Turn Context via Session ID) #7317 — Multi-session visibility

UI / Visualization:

• [FEATURE] Tree view for parallel agent monitoring #17425 — Tree view for parallel agent monitoring (the closest existing request, but bare-bones)
• [Feature Request] Extensible UI regions for persistent session context and activity indicators #18455, [FEATURE] Include session compact count in statusline JSON input #16512, [FEATURE] Rich Process State and Health Monitoring for Background Commands #7838 — Task/UI improvements

Proposed Solution

A built-in real-time dashboard with two companion proposals targeting different surfaces, sharing the same infrastructure:

┌─────────────────────────────────────────────────────┐
│                 Shared Infrastructure                │
│  Agent Registry · Enriched Hooks · Enriched         │
│  Statusline · Session Discovery · JSONL Transcripts │
└─────────────┬───────────────────────┬───────────────┘
              │                       │
    ┌─────────▼─────────┐   ┌────────▼────────────┐
    │  Proposal A: TUI   │   │  Proposal B: Desktop │
    │  (CLI terminal)    │   │  (Claude Desktop)    │
    │  React + Ink       │   │  React + Electron    │
    │  Alt screen buffer │   │  Sidebar / Split     │
    │  Vim keybindings   │   │  Canvas timeline     │
    │  ASCII tree        │   │  SVG charts          │
    └────────────────────┘   └──────────────────────┘

Proposal A: TUI Dashboard (CLI)

A full-screen overlay activated via /dashboard or Ctrl+Shift+D:

╔══════════════════════════════════════════════════════════════════════════════════╗
║ [A: feature/auth ↑87%]  [B: fix/sweep ↑34%]  [C: docs/glossary ✓]     Ctrl+D ║
╠════════════════════════════════════╦══════════════════════╦════════════════════════╣
║ ▼ Main Agent (opus-4-6)        ●  ║ Tasks (5)            ║ Session A              ║
║   ├─ Research TUI tools     2m41s ║ ✓ 1 Research TUI  2m ║ Branch: feature/auth   ║
║   │  └─ general (sonnet)    ✓     ║ ● 2 Research CC   4m ║ Model:  opus-4-6       ║
║   ├─ Research CC internals  4m05s ║ ● 3 Write design 33s ║ Context ████████░░ 87% ║
║   │  └─ general (sonnet)    ◐     ║ ○ 4 Run tests  ⊣3   ║ Tokens: 142k/38k       ║
║   ├─ Write design doc        33s  ║ ○ 5 Deploy     ⊣4   ║ Cost:   $4.82          ║
║   │  └─ (working...)        ●     ║                      ║ Runtime: 12m 34s       ║
║   ├─ Run tests           pending  ╠══════════════════════╣ Agents: 3● 1✓ 1○      ║
║   │  └─ ···                       ║▸Agent: Research CC   ║ Compacts: 2            ║
║   └─ Deploy              pending  ║ ✓ Search htop/btop   ╠════════════════════════╣
║      └─ ···                       ║ ✓ Search k9s/lazy    ║▸general (sonnet)       ║
║                                   ║ ● Search CC tools    ║ ID:   a597243          ║
║                                   ║                      ║ Status: ◐ waiting      ║
║                                   ║ Tool calls: 66       ║ Context ██████░░░ 38%  ║
║                                   ║ Files: 0w 0e         ║ Tokens: 54k/13k        ║
║                                   ║                      ║ Cost:   $0.41          ║
║                                   ║                      ║ Runtime: 4m 05s        ║
║                                   ║                      ║ ● WebSearch 3.2s ago   ║
╠════════════════════════════════════╩══════════════════════╩════════════════════════╣
║ Activity (follow)                                                          [f]/  ║
║ 12:34:07 [Main]    Edit Sources/CameraFeature/Views/CaptureView.swift            ║
║ 12:34:09 [Agent 1] WebSearch "ratatui tree widget 2026"                          ║
║ 12:34:14 [Agent 1] WebFetch github.com/nyanko3141592/tmuxcc                     ║
║ 12:34:18 [Agent 1] ✓ Complete — returned 4.2k chars to Main                     ║
╠══════════════════════════════════════════════════════════════════════════════════╣
║ j/k:navigate  Enter:expand  Tab:session  d:detail  f:follow  /:filter  q:exit  ║
╚══════════════════════════════════════════════════════════════════════════════════╝

Layout: Session tab bar (top) → three-column body (Agent Tree 40% | Tasks 28% | Stats 32%) → Activity stream (bottom)

Key features:

• First full-screen alternate screen buffer overlay in Claude Code
• Vim-style navigation (j/k, Enter, Tab, / filter)
• Unicode tree rendering with status icons (● running, ◐ waiting, ✓ complete, ✗ failed, ○ pending)
• Master-detail: selecting an agent updates the stats and task panels
• Inline approval prompts in the activity stream (y/n)
• Replay mode with transport controls for completed sessions

Proposal B: Desktop Dashboard (Claude Desktop Code Mode)

A persistent sidebar panel for Claude Desktop's Code mode:

Desktop-exclusive features not possible in TUI:

Required Infrastructure (Shared by Both Proposals)

These are the prerequisites many existing issues are requesting:

Comparison: TUI vs Desktop

Existing Community Tools (Gap Analysis)

Community tools demonstrate strong demand but hit fundamental limitations:

All of these would be unnecessary if the dashboard were built-in.

Alternative Solutions

1. Status quo + external tools — community builds on hooks. Limited by missing agent_id in payloads. Fragmented, no standard.
2. Enriched statusline only — expose data but let users build their own UI. Lower effort but doesn't solve the problem for most users.
3. Built-in dashboard (this proposal) — first-party experience that works out of the box. Higher effort but solves the problem completely.

Priority

High - Important for my workflow

Feature Category

CLI commands and flags

Use Case Example

Scenario: User asks Claude to plan and implement a feature across 5 files.

Claude spawns 3 parallel agents: Explore (codebase research), Plan (architecture design), and Bash (running tests). Each agent makes dozens of tool calls over 10+ minutes.

Today: User sees interleaved tool call summaries in the chat. No way to tell which agent is doing what, which is stuck, or how much context each has consumed. If an agent needs approval, it's buried in scroll.

With Dashboard: User presses Ctrl+Shift+D and sees the full agent tree with live status, per-agent context/cost, a task checklist, and an activity stream. They approve a pending action inline, see one agent is at 87% context (about to compact), and switch to check another session running on a different branch — all without leaving the terminal.

Full Technical Design

Complete technical design documents, ADRs, and mockups:

Repository: https://github.com/woodrowpearson/claude-code-agent-dashboard-proposal

Additional Context

• Claude Code uses React + Ink with Anthropic's custom differential renderer. The TUI proposal builds on this existing stack.
• Alternate screen buffers are documented as a "future consideration" by the team — this would be the first such implementation.
• Both proposals can be phased: Phase 1 (infrastructure + TUI), Phase 2 (Desktop). Or developed in parallel since they share the data layer.
• The infrastructure requirements (Agent Registry, enriched hooks) benefit the entire ecosystem of community tools, not just this dashboard.