Skip to content
Back

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-tree
MCP
Agents · 2 running · 1 needs you · 1 failed
Waiting on 1 agent2m 14s
Reading 14 files48s
Needs approval: run `cargo test`31s
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

  • One tool call in one line: use Tool call instead.
  • The agent's task list: use Todo list instead.
  • One job split into hundreds of small tasks across a pool of workers: use Task grid instead.

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-tree
Rust
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 · 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 · 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

PropTypeDefaultDescription
graphrequiredRunGraph—The graph.
nowrequiredClockMs—Shared clock.
variantString"indented"`indented`, `rail`, `dock`, `inline-wrapper` or `terminal`.
display_depthusize3Levels shown before folding (3).
max_childrenusize8Siblings shown before "+ n more" (8).
collapsedVec<String>Default::default()Initially collapsed node ids.
on_focusEventHandler<String>—Row pressed: focus that agent.
on_reviewEventHandler<String>—Review pressed on an agent that needs you.

Read from the Rust signature and doc comments.

Keyboard interactions

KeyAction
↑or↓Move between agents
←or→Collapse / expand
EnterFocus 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 tree with treeitems, 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 with spring.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.travel 240 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 per dur.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/canvas only): pan the node canvas; rows themselves are not reorderable (order is spawn order).
Timing
TransitionDurationDelayEasing / springStaggerFrame rate
Row spawn unfold200 ms—spring.snap30 ms, cap 660 Hz during
Connector draw160 mswith unfoldease.outfollows rows60 Hz
Submitted pulse (Starting)400 ms × 1—ease.out—60 Hz
Dot breathing (Working)1600 ms loop—sinephase-locked to shared clock30 Hz (max 8 rows)
Verb / summary swap180 ms, 4 pxmin 2 s between swapsease.out + spring.snap widthword diff 30 ms60 Hz
Roll-up badge pop120 ms—spring.snap—60 Hz
Needs-you ring400 ms × 1—ease.out—60 Hz
Waiting tip2000 ms loop (300 ms turn)—ease.in-out—30 Hz
Collapse / expand180 ms; chevron dur.fast 120 ms—spring.snap—60 Hz
Focus breadcrumb travel240 ms—ease.in-out—60 Hz
Pane crossfade on focus160 ms—ease.out—60 Hz
Result chip travel240 ms (cap 260)120 ms condense firstease.in-out80 ms, cap 460 Hz
Done / failed morph200 ms / 160 ms + 2 × 3 px nudge 240 ms—spring.snap / linear—60 Hz
Dim finished rows300 msafter 4 sease.out—30 Hz
Stall ramp / snap-back2 s / 200 msafter 5 s silent (soft)linear OKLab / ease.out—30 Hz
Reduced motionrows 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—linearnone1 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 use tool_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 SubagentTree from oxyn_dioxus and include RUN_CSS plus the token stylesheet once.
  • A GPUI version exists: SubagentTreeEl in oxyn_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.

Guides

Oxyn · 74 free components · 264 Pro components · 96 screens · 20 blocks · Dioxus and GPUI