Agent Trail
The steps an agent works through as one quiet trail: a header with the agent's mark, the task and 3/5; done steps with a check and their time; the running step shimmering what it does with a live timer, a short fading light running down the trail into the sub-step it is on; long sub-step lists fold to five (+N earlier, +N more); a gated step waits with a dashed ring and Approval, then Needs you opens Approve and Decline; declined steps are struck through; each step shows its tool's coloured logo. RTL, keyboard and live-region built in.
oxyn add agent-trailFix the checkout crash
2/5- Read the bug report8s
- Reproduce the crash34s
- Found the empty-cart casesrc/…artWrapper.tsx:1284
- Added a guard and 2 tests+18 −3
- Running the test suite182/214
- Check the e2e checkout
- Write the release note
- Open a pull requestApproval
rsx! {
AgentTrail {
trail: trail() // Trail { title, agent, steps: [TrailStep { tool, gate, ask, sub, details, .. }] },
now: clock.now(),
on_approve: move |i| trail.write().approve(i, now),
on_decline: move |i| trail.write().decline(i),
}
}Rendered from Rust at build time · goes live when visible
When to use
- The steps an agent works through as one quiet trail, for a chat answer, a side panel or a task card: what is done, what it is doing now and what comes next, and a stop that needs your approval coming into view before it is reached.
When not to use
- An agent asks before it acts: use Approval Card instead.
- Several open requests in one card: use Approval pager instead.
- An agent's question in its own card above the composer: use Decision Card instead.
Installation
Agent Trail 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.
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add agent-trailuse crate::oxyn::{AgentTrail, STATUS_INDICATOR_CSS};Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{AgentTrail, STATUS_INDICATOR_CSS};
Usage
rsx! {
AgentTrail {
trail: trail() // Trail { title, agent, steps: [TrailStep { tool, gate, ask, sub, details, .. }] },
now: clock.now(),
on_approve: move |i| trail.write().approve(i, now),
on_decline: move |i| trail.write().decline(i),
}
}Examples
Running
Step 3 testing: the light runs down to the running sub-step, live timer.
Fix the checkout crash
2/5- Read the bug report8s
- Reproduce the crash34s
- Found the empty-cart casesrc/…artWrapper.tsx:1284
- Added a guard and 2 tests+18 −3
- Running the test suite182/214
- Check the e2e checkout
- Write the release note
- Open a pull requestApproval
Code
rsx! {
AgentTrail {
trail: trail() // Trail { title, agent, steps: [TrailStep { tool, gate, ask, sub, details, .. }] },
now: clock.now(),
on_approve: move |i| trail.write().approve(i, now),
on_decline: move |i| trail.write().decline(i),
}
}Needs you
The gated PR step waits: Needs you opens Approve and Decline.
Fix the checkout crash
4/5- Read the bug report8s
- Reproduce the crash34s
- Write the release note12s
- Open a pull request
Code
rsx! {
AgentTrail {
trail: trail() // Trail { title, agent, steps: [TrailStep { tool, gate, ask, sub, details, .. }] },
now: clock.now(),
on_approve: move |i| trail.write().approve(i, now),
on_decline: move |i| trail.write().decline(i),
}
}Declined
You said no: the step is struck through.
Fix the checkout crash
5/5- Read the bug report8s
- Reproduce the crash34s
- Write the release note12s
- Open a pull requestDeclined
Code
rsx! {
AgentTrail {
trail: trail() // Trail { title, agent, steps: [TrailStep { tool, gate, ask, sub, details, .. }] },
now: clock.now(),
on_approve: move |i| trail.write().approve(i, now),
on_decline: move |i| trail.write().decline(i),
}
}Failed
The patch failed.
Fix the checkout crash
2/5- Read the bug report8s
- Reproduce the crash34s
- Failed
- Write the release note
- Open a pull requestApproval
Code
rsx! {
AgentTrail {
trail: trail() // Trail { title, agent, steps: [TrailStep { tool, gate, ask, sub, details, .. }] },
now: clock.now(),
on_approve: move |i| trail.write().approve(i, now),
on_decline: move |i| trail.write().decline(i),
}
}Folded
Twelve sub-steps fold to five around the running one: +N earlier, +N more.
Fix the checkout crash
2/5- Read the bug report8s
- Reproduce the crash34s
- Found the empty-cart casesrc/…artWrapper.tsx:1284
- Added a guard and 2 tests+18 −3
- Running the test suite182/214
- Check the e2e checkout
- Update the snapshot
- Write the release note
- Open a pull requestApproval
Code
rsx! {
AgentTrail {
trail: trail() // Trail { title, agent, steps: [TrailStep { tool, gate, ask, sub, details, .. }] },
now: clock.now(),
on_approve: move |i| trail.write().approve(i, now),
on_decline: move |i| trail.write().decline(i),
}
}Card
As a card, every step done.
Fix the checkout crash
5/5- Read the bug report8s
- Reproduce the crash34s
- Write the release note12s
- Open a pull request<1s
Code
rsx! {
AgentTrail {
trail: trail() // Trail { title, agent, steps: [TrailStep { tool, gate, ask, sub, details, .. }] },
now: clock.now(),
variant: "card",
on_approve: move |i| trail.write().approve(i, now),
on_decline: move |i| trail.write().decline(i),
}
}Inline
Inline, no header rule, dense.
Fix the checkout crash
2/5- Read the bug report8s
- Reproduce the crash34s
- Found the empty-cart casesrc/…artWrapper.tsx:1284
- Added a guard and 2 tests+18 −3
- Running the test suite182/214
- Check the e2e checkout
- Write the release note
- Open a pull requestApproval
Code
rsx! {
AgentTrail {
trail: trail() // Trail { title, agent, steps: [TrailStep { tool, gate, ask, sub, details, .. }] },
now: clock.now(),
variant: "inline",
dense: true,
on_approve: move |i| trail.write().approve(i, now),
on_decline: move |i| trail.write().decline(i),
}
}Rtl
Right to left: the rail moves to the right edge.
Fix the checkout crash
2/5- Read the bug report8s
- Reproduce the crash34s
- Found the empty-cart casesrc/…artWrapper.tsx:1284
- Added a guard and 2 tests+18 −3
- Running the test suite182/214
- Check the e2e checkout
- Write the release note
- Open a pull requestApproval
Code
rsx! {
AgentTrail {
trail: trail() // Trail { title, agent, steps: [TrailStep { tool, gate, ask, sub, details, .. }] },
now: clock.now(),
rtl: true,
on_approve: move |i| trail.write().approve(i, now),
on_decline: move |i| trail.write().decline(i),
}
}Empty
No steps yet.
Fix the checkout crash
0/0No steps yet
Code
rsx! {
AgentTrail {
trail: trail() // Trail { title, agent, steps: [TrailStep { tool, gate, ask, sub, details, .. }] },
now: clock.now(),
on_approve: move |i| trail.write().approve(i, now),
on_decline: move |i| trail.write().decline(i),
}
}API reference
AgentTrail
| Prop | Type | Default | Description |
|---|---|---|---|
trailrequired | Trail | — | Trail. |
nowrequired | ClockMs | — | Shared clock. |
substeps | bool | true | Show sub-steps (the running step opens; others open with a click). |
dense | bool | Default::default() | Dense rows. |
variant | String | "plain" | `plain` · `card` · `inline`. |
rtl | bool | Default::default() | Right-to-left. |
on_approve | Option<EventHandler<usize>> | Default::default() | A waiting step was approved (index). With this or `on_decline`, Needs you is a button. |
on_decline | Option<EventHandler<usize>> | Default::default() | A waiting step was declined (index). |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| Tab | Each step with sub-steps, +N earlier / +N more, Needs you |
| EnterorSpace | Open or close a step's sub-steps; show every sub-step |
| Enter | On Needs you: open Approve and Decline, focus on Approve |
| Escape | Close the answer panel |
Accessibility
- An ordered list named after the task; the running step and sub-step carry aria-current=step.
- The header count reads 3 of 5 steps done; each step reads its title, state and time.
- A step with sub-steps toggles them and reports aria-expanded; times and details keep their direction in RTL.
- A polite live region says Approved or Declined; the focus outline appears only when moving by keyboard.
From the spec
- An ordered list named after the task; the running step and its running sub-step carry
aria-current="step". - The header count reads "3 of 5 steps done"; each row reads "Read the bug report – Done, 8s"; a step with sub-steps toggles them and reports
aria-expanded. - Times, badges and details read in their own direction (
<1sstays<1sin RTL). - A polite live region says "Approved: …" or "Declined".
- The focus outline appears only when moving by keyboard (
:focus-visible), in light and dark.
Motion & interaction
Timing
| Motion | Timing | Reduced motion |
|---|---|---|
| Light down the rail | 1.8 s cubic-bezier(.45,0,.3,1), loop, fades in and out | still, at the target |
| Running ring | 0.9 s linear spin | 3 s |
| Status shimmer | 1.6 s linear | static muted text |
| Live timer | ticks with the host clock | same |
Responsive behaviour
- Rows are fixed: 32 px a step, 24 px a sub-step, 40 and 28 px on touch screens.
- Long sub-step lists fold to five around the running one; the right side never takes more than 40%.
- Right to left: the rail moves to the right edge and the branch bends the other way.
Edge cases (spec)
Rows are fixed, so a changing status, timer or detail never moves another row; long titles end in … with the full text on hover; long sub-step lists fold to five around where the agent is.
Notes for AI
- Import
AgentTrailfromoxyn_dioxusand includeSTATUS_INDICATOR_CSSplus the token stylesheet once. - A GPUI version exists:
AgentTrailElinoxyn_gpui. - Props to set first:
trail,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.