Skip to content
Back

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-trail
MCP
Claude

Fix the checkout crash

2/5
  1. Read the bug report8s
  2. 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
  3. Write the release note
  4. Open a pull request
    Approval
Dioxus
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.

Terminal
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add agent-trail
Rust
use 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

Dioxus · rust
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.

Claude

Fix the checkout crash

2/5
  1. Read the bug report8s
  2. 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
  3. Write the release note
  4. Open a pull request
    Approval
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.

Claude

Fix the checkout crash

4/5
  1. Read the bug report8s
  2. Reproduce the crash34s
  3. Write the release note12s
  4. 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.

Claude

Fix the checkout crash

5/5
  1. Read the bug report8s
  2. Reproduce the crash34s
  3. Write the release note12s
  4. Open a pull request
    Declined
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.

Claude

Fix the checkout crash

2/5
  1. Read the bug report8s
  2. Reproduce the crash34s
  3. Failed
  4. Write the release note
  5. Open a pull request
    Approval
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.

Claude

Fix the checkout crash

2/5
  1. Read the bug report8s
  2. 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
  3. Write the release note
  4. Open a pull request
    Approval
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.

Claude

Fix the checkout crash

5/5
  1. Read the bug report8s
  2. Reproduce the crash34s
  3. Write the release note12s
  4. 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.

Claude

Fix the checkout crash

2/5
  1. Read the bug report8s
  2. 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
  3. Write the release note
  4. Open a pull request
    Approval
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.

Claude

Fix the checkout crash

2/5
  1. Read the bug report8s
  2. 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
  3. Write the release note
  4. Open a pull request
    Approval
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.

Claude

Fix the checkout crash

0/0

No 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

PropTypeDefaultDescription
trailrequiredTrail—Trail.
nowrequiredClockMs—Shared clock.
substepsbooltrueShow sub-steps (the running step opens; others open with a click).
denseboolDefault::default()Dense rows.
variantString"plain"`plain` · `card` · `inline`.
rtlboolDefault::default()Right-to-left.
on_approveOption<EventHandler<usize>>Default::default()A waiting step was approved (index). With this or `on_decline`, Needs you is a button.
on_declineOption<EventHandler<usize>>Default::default()A waiting step was declined (index).

Read from the Rust signature and doc comments.

Keyboard interactions

KeyAction
TabEach step with sub-steps, +N earlier / +N more, Needs you
EnterorSpaceOpen or close a step's sub-steps; show every sub-step
EnterOn Needs you: open Approve and Decline, focus on Approve
EscapeClose 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 (<1s stays <1s in 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
MotionTimingReduced motion
Light down the rail1.8 s cubic-bezier(.45,0,.3,1), loop, fades in and outstill, at the target
Running ring0.9 s linear spin3 s
Status shimmer1.6 s linearstatic muted text
Live timerticks with the host clocksame

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 AgentTrail from oxyn_dioxus and include STATUS_INDICATOR_CSS plus the token stylesheet once.
  • A GPUI version exists: AgentTrailEl in oxyn_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.

Guides

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