Install

npx ax-depute@latest add orchestrator-view

pnpm dlx ax-depute@latest add orchestrator-view

yarn dlx ax-depute@latest add orchestrator-view

bunx ax-depute@latest add orchestrator-view

A recursive tree graph representing the Orchestrator and all of its spawned worker sub-agents. It provides a macro-view of the swarm's structure and highlights blocked or failed nodes that require human attention.

Orchestrator-PrimeOrchestratorFetching latest API documentation from external source
Working
- Researcher-AResearcher
  Idle
  - Retrieval-BotRetrievalAnalyzing repository structure for refactor opportunities
    Working
  - Summarizer-XSummarizerCross-referencing data against internal knowledge base
    Working
- Code-Writer-1Code WriterGenerating TypeScript interfaces from JSON schema
  Blocked
  - Validator-3Validator
    Idle
  - QA-InspectorQA InspectorAnalyzing repository structure for refactor opportunities
    Working
- Data-AnalystData Analyst
  Idle

Interactive StorybookView all states, toggle props, and test edge cases.

Basic usage

import { useState } from 'react';
import { OrchestratorView } from '@/components/OrchestratorView';
import type { OrchestratorNode } from '@/components/OrchestratorView/OrchestratorView.types';

const mockSwarm: OrchestratorNode[] = [
  {
    id: 'orch_1',
    label: 'Main Router',
    role: 'Orchestrator',
    status: 'working',
    currentTask: 'Delegating work to sub-agents...',
    children: [
      {
        id: 'sub_1',
        label: 'Data Researcher',
        role: 'Search API',
        status: 'completed',
      },
      {
        id: 'sub_2',
        label: 'Code Writer',
        role: 'React Expert',
        status: 'blocked',
        currentTask: 'Waiting for missing API key',
      }
    ]
  }
];

export function App() {
  const [selectedId, setSelectedId] = useState<string>('orch_1');

  return (
    <div className="p-4 border border-zinc-200 dark:border-zinc-800 rounded-lg max-w-md">
      <OrchestratorView 
        nodes={mockSwarm} 
        selectedNodeId={selectedId}
        onNodeClick={(node) => setSelectedId(node.id)}
      />
    </div>
  );
}

Props

Prop	Type	Default	Description
`nodes`	`OrchestratorNode[]`	`undefined`	Hierarchical tree data. Usually contains a single root node representing the main orchestrator agent.
`onNodeClick`	`(node: OrchestratorNode) => void`	`undefined`	Callback fired when the user clicks on an individual node in the tree.
`selectedNodeId`	`string`	`undefined`	The `id` of the currently selected node, used to highlight the active agent in the tree.
`className`	`string`	`undefined`	Additional CSS class for the root element.

Types

`OrchestratorNode`

export type AgentStatus = 'idle' | 'working' | 'blocked' | 'failed' | 'completed';

export interface OrchestratorNode {
  id: string;
  label: string;
  status: AgentStatus;
  role?: string;
  currentTask?: string;
  children?: OrchestratorNode[];
}

Solution Patterns

Orchestrator View acts as the navigation tree for a complex, hierarchical swarm.

Use it as the left-pane side navigation in a specialized dashboard.
Pair it with Swarm Monitor at the top of the viewport for aggregate metrics spanning the entire tree.
When an individual node is clicked (onNodeClick), render a Plan Card + Tool Trace + Run Controls trio in the main right-hand pane to inspect that specific sub-agent.

Design rationale

1. The Macro/Micro Split
When multiple agents are running in a swarm, a single terminal log or chat thread becomes impossible to follow. Orchestrator View serves as the "macro" view—a structural map of who is doing what. Clicking a node typically updates an adjacent pane with the "micro" view (a standard Plan Card + Tool Trace for that specific agent).

2. Exception Highlighting
The tree naturally collapses cognitive load by burying successful (completed) and waiting (idle) agents. However, blocked and failed nodes use high-contrast color codes to draw the supervisor's eye directly to the nodes requiring intervention, regardless of how deep they are nested.

3. Depth Coding
To solve the "sea of gray boxes" problem, the left border of each node is color-coded by depth (e.g., Indigo → Sky → Emerald → Amber). This provides an instant visual anchor for nesting levels, even when inner branches are expanded.

Orchestrator View