Sub-agent tree
Who started whom: an orchestrator and its sub-agents with state, time and results, approvals surfaced in place, depth and sibling limits, as an indented tree, a rail, a dock or a terminal.
oxyn add subagent-treeAgents · 2 running · 1 needs you · 1 failed
Waiting on 1 agent2m 14s
Reading 14 files48s
Needs approval: run `cargo test`31s
Returned · 3 fixtures12s
Returned · 2 findings1m 05s
Failed · tool error20s
Dioxus
rsx! {
SubagentTree {
graph: run.graph(),
now: clock.now(),
on_review: move |id: String| open_approval(id),
}
}Rendered from Rust at build time · goes live when visible
When to use
- A parent agent delegates: it spawns a researcher, a test-runner, a reviewer, and they may spawn their own helpers.
- The user wants to know who is working on what, who is stuck, who needs me, and what came back without opening every child.
- The tree answers that in one glance and lets the user focus one child (read its transcript, steer it, stop it) and come back.
When not to use
Installation
Sub-agent tree is free and MIT. The oxyn CLI copies its code, and the components it needs, into src/oxyn/ of your Dioxus or GPUI project, so it is yours to change.
Terminal
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add subagent-treeRust
use crate::oxyn::{SubagentTree, RUN_CSS};Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{SubagentTree, RUN_CSS};
Usage
Dioxus · rust
rsx! {
SubagentTree {
graph: run.graph(),
now: clock.now(),
on_review: move |id: String| open_approval(id),
}
}Examples
Indented
The full tree.
Agents · 2 running · 1 needs you · 1 failed
Waiting on 1 agent2m 14s
Reading 14 files48s
Needs approval: run `cargo test`31s
Returned · 3 fixtures12s
Returned · 2 findings1m 05s
Failed · tool error20s
Code
rsx! {
SubagentTree {
graph: run.graph(),
now: clock.now(),
on_review: move |id: String| open_approval(id),
}
}Rail
A side rail.
Agents · 2 running · 1 needs you · 1 failed
Waiting on 1 agent2m 14s
├─Reading 14 files48s
├─Needs approval: run `cargo test`31s
│ └─Returned · 3 fixtures12s
├─Returned · 2 findings1m 05s
└─Failed · tool error20s
Code
rsx! {
SubagentTree {
graph: run.graph(),
now: clock.now(),
variant: "rail",
on_review: move |id: String| open_approval(id),
}
}Dock
Docked summary.
Agents · 2 running · 1 needs you · 1 failed
Waiting on 1 agent2m 14s
Reading 14 files48s
Needs approval: run `cargo test`31s
Failed · tool error20s
2 done
Code
rsx! {
SubagentTree {
graph: run.graph(),
now: clock.now(),
variant: "dock",
on_review: move |id: String| open_approval(id),
}
}Terminal
Terminal tree.
Agents · 2 running · 1 needs you · 1 failed
⠋ Orchestrator Waiting on 1 agent 2m 14s
├─⠙ Researcher Reading 14 files 48s
├─⚠ Test runner Needs approval: run `cargo test` 31s
│ └─✓ Fixture gen Returned · 3 fixtures 12s
├─✓ Reviewer Returned · 2 findings 1m 05s
└─✗ Docs writer Failed · tool error 20s
Code
rsx! {
SubagentTree {
graph: run.graph(),
now: clock.now(),
variant: "terminal",
on_review: move |id: String| open_approval(id),
}
}API reference
SubagentTree
| Prop | Type | Default | Description |
|---|---|---|---|
graphrequired | RunGraph | — | The graph. |
nowrequired | ClockMs | — | Shared clock. |
variant | String | "indented" | `indented`, `rail`, `dock`, `inline-wrapper` or `terminal`. |
display_depth | usize | 3 | Levels shown before folding (3). |
max_children | usize | 8 | Siblings shown before "+ n more" (8). |
collapsed | Vec<String> | Default::default() | Initially collapsed node ids. |
on_focus | EventHandler<String> | — | Row pressed: focus that agent. |
on_review | EventHandler<String> | — | Review pressed on an agent that needs you. |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| ↑or↓ | Move between agents |
| ←or→ | Collapse / expand |
| Enter | Focus that agent's transcript, or review its approval |
Accessibility
- role=tree with treeitems, aria-level, aria-setsize, aria-posinset and aria-expanded.
- Rows read in full ("Test runner, sub-agent of Orchestrator, needs your approval").
- Failures and approvals are announced assertively; at most one announcement per 5 s.
From the spec
- Role
treewithtreeitems,aria-level,aria-setsize,aria-posinset,aria-expanded. GPUI maps to the platform tree role. - Labels: "Test runner, sub-agent of Orchestrator, needs your approval: run cargo test, waiting 31 seconds"; "Reviewer, done after 1 minute 5 seconds, returned 2 findings"; truncated row: "4 more nested agents, collapsed".
- Live region (polite): sub-agent started (batched: "3 sub-agents started"), finished with result, failed (assertive), needs approval (assertive), all done. At most one announcement per 5 s per tree; verb changes are not announced.
- Contrast: names and verbs ≥ 4.5:1; identity swatches ≥ 3:1 against the row and always paired with the name; state is carried by glyph + text (●, ⚠, ✓, ✕, ■, ⊘), never colour alone.
- Focus order: tree header (collapse all) → rows in tree order → row actions via Tab inside the focused row. Focusing a child moves focus to the child transcript's first message heading; Back returns focus to the same row.
- Reduced motion: §5 last row; meaning never depends on the travel animation (receipt line carries it).
Motion & interaction
- Spawn. A new child row unfolds under its parent (height 0 → 32 px) while its connector line draws from the parent's rail down to the new row; siblings below slide down. Rows spawned within 100 ms of each other stagger 30 ms (cap 6,
stagger). The new row's dot starts with the submitted pulse. - Verb swap. Same as the status strip: 180 ms crossfade with 4 px slide, width tween
spring.snap. Summary text from the adapter (cheap status lines, ~30 s cadence per [R024]) animates only the changed words (diff by word; unchanged prefix stays still); minimum 2 s between swaps per row. - Roll-up badge. When a hidden descendant changes urgency, the collapsed parent's badge does one 120 ms scale 1 → 1.15 → 1 pop; amber "needs you" badges add a single 400 ms ring pulse. No looping.
- Collapse / expand. Chevron rotates 90° (
dur.fast); children's height animates withspring.snap; connectors retract with the rows. Collapsing a running branch keeps its roll-up badge live. - Focus a child. The focused row's name slides into the breadcrumb (
dur.travel240 ms,ease.in-out) while the content pane crossfades to that child's transcript; the tree narrows to a rail (icons + dots only) in layouts under 720 px. Back reverses the travel. - Result bubbling up. On
Done, a result chip ("2 findings") condenses from the row's verb text, then travels along the connector to the parent row (240 ms,ease.in-out, max 260 ms perdur.travel) and lands as a "↗ returned" marker on the parent and a receipt line in the parent's transcript ("Reviewer returned · 2 findings"). The child's row settles to ✓ + result line. Many children finishing together: chips queue at 80 ms intervals, max 4 animated, the rest appear in place. - Needs you. The row's dot stops breathing and does the waiting tip (hourglass-style turn every 2 s, as in the status strip); the row background takes a 6 % amber wash. The tree header count rolls ("1 needs you").
- Done / failed. Dot morphs to ✓ (scale 0.6 → 1,
spring.snap) or ✕ with a 2-cycle 3 px nudge, then goes still. Finished rows dim text to secondary after 4 s (still ≥ 4.5:1). - Hover. Row reveals trailing actions (focus, stop) and a tooltip: model, started at, tokens, worktree or branch if the app supplies them.
- Drag (Pro
subagent-tree/canvasonly): pan the node canvas; rows themselves are not reorderable (order is spawn order).
Timing
| Transition | Duration | Delay | Easing / spring | Stagger | Frame rate |
|---|---|---|---|---|---|
| Row spawn unfold | 200 ms | — | spring.snap | 30 ms, cap 6 | 60 Hz during |
| Connector draw | 160 ms | with unfold | ease.out | follows rows | 60 Hz |
| Submitted pulse (Starting) | 400 ms × 1 | — | ease.out | — | 60 Hz |
| Dot breathing (Working) | 1600 ms loop | — | sine | phase-locked to shared clock | 30 Hz (max 8 rows) |
| Verb / summary swap | 180 ms, 4 px | min 2 s between swaps | ease.out + spring.snap width | word diff 30 ms | 60 Hz |
| Roll-up badge pop | 120 ms | — | spring.snap | — | 60 Hz |
| Needs-you ring | 400 ms × 1 | — | ease.out | — | 60 Hz |
| Waiting tip | 2000 ms loop (300 ms turn) | — | ease.in-out | — | 30 Hz |
| Collapse / expand | 180 ms; chevron dur.fast 120 ms | — | spring.snap | — | 60 Hz |
| Focus breadcrumb travel | 240 ms | — | ease.in-out | — | 60 Hz |
| Pane crossfade on focus | 160 ms | — | ease.out | — | 60 Hz |
| Result chip travel | 240 ms (cap 260) | 120 ms condense first | ease.in-out | 80 ms, cap 4 | 60 Hz |
| Done / failed morph | 200 ms / 160 ms + 2 × 3 px nudge 240 ms | — | spring.snap / linear | — | 60 Hz |
| Dim finished rows | 300 ms | after 4 s | ease.out | — | 30 Hz |
| Stall ramp / snap-back | 2 s / 200 ms | after 5 s silent (soft) | linear OKLab / ease.out | — | 30 Hz |
| Reduced motion | rows appear/disappear with an 80 ms opacity crossfade, no unfold or connector draw; no breathing (static ●), no tip (static ⏸); result chip does not travel: parent marker and receipt crossfade in; numbers swap; focus switches pane instantly with 80 ms fade | — | linear | none | 1 Hz (elapsed only) |
Responsive behaviour
- display_depth and max_children fold deep or wide trees into "+ n more".
Edge cases (spec)
- Long names / verbs. Name max 24 ch, verb truncates middle ("Editing src/…/auth.rs"); full text in the tooltip. Model-written summaries over 80 ch are clipped.
- Wide swarms. More than 8 children under one parent: first 8 by urgency (needs you, failed, running, then done by recency) and a "+ 12 more" row. More than 50 nodes total: rows virtualised; only visible rows tick.
- Deep trees. Display depth 3 by default (proposed); deeper levels fold into "+ n nested agents". Indent caps at 3 levels × 16 px; deeper indent shows a depth number chip (
d5) instead of more indent. Runtime refusals (Refused{DepthLimit}) are shown once per parent, not per attempt. - Cycles / missing parents from a buggy adapter: a node whose parent is unknown attaches to the root with an "unlinked" badge; cycles are broken at the second visit (debug log).
- Very fast children (< 150 ms
show_delay): no row animation; a finished child appears directly as ✓ in the "done" fold. - Very slow children (hours): elapsed compacts to
1h 02m; status summaries keep refreshing at the adapter's cadence; stall thresholds usetool_stall(120 s) while a tool runs. - Parent stopped. Stop on the parent stops all descendants by default; children that keep running (app says they are detached) become
Orphaned. - Approval from a deep child. Root header "1 needs you" plus the ancestors' roll-up badges form a path; Review opens the card without changing focus when the layout has room, otherwise focuses the child.
- RTL. Indentation and connectors mirror; elapsed and numbers stay LTR in bidi isolates; breadcrumb separator flips (‹).
- Tiny sizes (16–20 px rows). Dot (8 px) + name only; verb in tooltip; elapsed hidden under 200 px width; actions behind a ⋯ menu.
- Dense IDE panels. 28 px rows, 12 px dots, no result travel (instant marker), connectors 1.5 px.
- Touch. Rows 44 px hit target; swipe-left reveals Stop; long-press opens details.
- Slow networks. Rows keep last known state; the tree header shows "offline" once, rows dim to 60 %; no stall ramps while the transport reports reconnecting.
- Same colour twice (more than 8 agents): colours repeat; names and a 2-letter monogram in the swatch disambiguate.
Notes for AI
- Import
SubagentTreefromoxyn_dioxusand includeRUN_CSSplus the token stylesheet once. - A GPUI version exists:
SubagentTreeElinoxyn_gpui. - Props to set first:
graph,now. - It reads a clock (
now) for live timers; pass one clock for the whole page rather than one per component. - Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.