Subagent Tree

The tree of subagents a run spawned and what each is costing. Cost aggregates up the tree — a parent that spent 400 tokens itself and fanned out to children that spent 90,000 is cheap by its own line and ruinous in total.

src/components/ui/subagent-tree.tsx

About

From the component's own source, where it was written.

The tree of subagents a run spawned, and what each is costing.

HandoffTrail is a chain — one agent hands to the next. This is the other shape: a parent that fans out to several children at once, each of which may fan out again. Drawing that as a list loses the only thing that matters, which is who spawned whom.

**Cost is aggregated up the tree, not just reported per node.** A parent that spent 400 tokens itself and spawned six children that spent 90,000 between them is cheap by its own line and ruinous in total, and the per-node number is the one that gets read.

Depth is drawn with indentation and a rule rather than connector elbows: the tree is usually two or three levels and the elbows cost more in visual noise than they return in clarity.

Install

npx astralyx-ui add subagent-tree

Usage

import { SubagentTree } from '@/components/ui/subagent-tree'

<SubagentTree agents={agents} onSelect={openAgent} />

Composer

Change the props and the source below follows.

Subagents

56.6k tokens

Props

subtree totals

tsx

<SubagentTree
  agents={agents}
  showSubtreeTotals={true}
  onSelect={openAgent}
/>

Examples

A fan-out with one failure

tsx

<SubagentTree agents={agents} />

API

Generated from the source, so it cannot fall behind the code. One table per exported component, then hooks, functions and types.

`SubagentTree`

The tree of subagents a run spawned, and what each is costing.

Extends Omit<ComponentProps<'div'>, 'onSelect'>.

Prop	Type	Default	Description
agents	Subagent[]	required	{ id, name, task?, status?, tokens?, duration?, children? }. `tokens` is that agent alone, excluding its children.
onSelect	(agent: Subagent) => void	—	—
selectedId	string	—	—
formatTokens	(tokens: number) => string	defaultTokens	—
showSubtreeTotals	boolean	true	Show the aggregated subtree total beside a parent's own usage.
emptyLabel	string	'No subagents were spawned.'	—
label	string	'Subagents'	—

Functions

Function	Signature	Description
subtreeTokens	(agent: Subagent) => number	Exported. A node plus every descendant — the number that actually matters on a parent, and the one a per-node readout hides.

Types

`Subagent`

Field	Type	Description
id	string	—
name	string	—
task?	ReactNode	What it was asked to do.
status?	'running' \| 'done' \| 'failed'	—
tokens?	number	Tokens this agent used, excluding its children.
duration?	ReactNode	Already formatted.
children?	Subagent[]	—

Behaviour

Topic	Detail	Description
vs HandoffTrail	tree vs chain	A handoff is one agent passing to the next. This is a parent fanning out to several at once; drawing that as a list loses who spawned whom.