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

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] 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:

• #7881 — SubagentStop hook cannot identify which specific subagent finished (19 upvotes)
• #14859 — Agent Hierarchy in Hook Events + SubagentStart Hook (9 upvotes)
• #16424 — Expose Agent Context in Hook Event Payloads for Multi-Agent Observability (7 upvotes)
• #10052 — Expose current agent information for external monitoring
• #20921 — Event Subscriptions for Real-Time Agent Communication
• #10164 — Show sub-agent token usage in /context command
• #10388 — (Related agent monitoring)
• #24094 — Show model name in tool call UI for subagents

Per-Agent Resource Tracking:

• #22625 — Per-Subagent Token Usage Tracking
• #17431, #15434, #18550 — Cost/usage visibility

Session Management:

• #16901, #2562, #22995, #22617, #17536, #9306 — Session management improvements

Multi-Session:

• #17188, #16311, #20559, #18401, #7317 — Multi-session visibility

UI / Visualization:

• #17425 — Tree view for parallel agent monitoring (the closest existing request, but bare-bones)
• #18455, #16512, #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  ║
╚══════════════════════════════════════════════════════════════════════════════════╝

!TUI Dashboard Mockup

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 Dashboard Mockup

Desktop-exclusive features not possible in TUI:

| Feature | Description |
|---------|-------------|
| Persistent sidebar | Non-blocking — conversation continues while Dashboard updates |
| Timeline / Gantt view | Canvas-rendered horizontal swimlanes with zoom/pan |
| Cost projection | Real-time "$/min" burn rate with budget alerts |
| Native notifications | macOS/Windows alerts for agent complete, failed, approval needed |
| File heatmap | Directory tree with per-agent color-coded access bars |
| Export | PNG, HTML (interactive replay), JSON, CSV, Markdown |
| Detachable window | Float Dashboard on second monitor |

Required Infrastructure (Shared by Both Proposals)

These are the prerequisites many existing issues are requesting:

| Requirement | Related Issues | Status |
|-------------|---------------|--------|
| Agent Registry — internal service maintaining agent relationships | #14859, #16424 | Not started |
| agent_id in hook payloads — attribute events to specific agents | #7881, #14859, #16424, #10052 | Not started (most requested) |
| SubagentStart hook — know when agents spawn | #14859 | Not started |
| Per-agent metrics — context %, tokens, cost per agent | #22625, #10164 | Not started |
| Enriched statusline — agent tree data in status JSON | #10052, #14306 (closed as dup) | Not started |
| Session discovery — cross-session visibility | #17188, #16311 | Not started |

Comparison: TUI vs Desktop

| Aspect | TUI (Proposal A) | Desktop (Proposal B) |
|--------|-------------------|----------------------|
| Platform | Claude Code CLI (terminal) | Claude Desktop Code mode |
| Framework | React + Ink + custom renderer | React + Electron |
| Activation | /dashboard, Ctrl+Shift+D | Cmd+Shift+D, sidebar toggle |
| Layout | Full-screen overlay | Sidebar, split pane, detached window |
| View modes | Tree only | Tree, Timeline, Cost, Heatmap |
| Navigation | Keyboard only (vim-style) | Mouse + keyboard |
| Data viz | ASCII bars, text tables | SVG charts, Canvas timeline |
| Replay | Transport controls in overlay | Interactive timeline scrubber |

Existing Community Tools (Gap Analysis)

Community tools demonstrate strong demand but hit fundamental limitations:

| Tool | Approach | Limitation |
|------|----------|------------|
| TmuxCC | Polls tmux panes | No true tree, no per-agent stats |
| claude-dashboard | k9s-style session list | Flat list, no hierarchy |
| ATM | Hook-driven daemon | No nested tree, no task panel |
| claude-code-hooks-observability | Web dashboard | Web-only, no tree, no replay |
| Claude HUD | Statusline plugin | Single session, no tree |

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

| Document | Description |
|----------|-------------|
| TUI Technical Design | Component architecture, data model, API requirements, keybindings, replay mode |
| Desktop Technical Design | Desktop layout, view modes, exclusive features, component design |
| ADR-001: TUI Dashboard | Decision record with alternatives considered |
| ADR-002: Desktop Dashboard | Decision record for Desktop edition |

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.