Subagent
SaveA nested agent run with its name, task, live state, its own tool calls as Tool Call Cards, and its result, collapsible on a hairline rail.
- Category
- AI elements
- Version
- 0.1.0
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Subagent preview
Queued
No tool calls yet
Installation
npx @shakenui/cli add subagentReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add subagent --dry-runUsage
subagent-example.tsx
import { Subagent } from "@/components/shaken/agent/subagent";
export default function SubagentExample() {
return (
<div className="grid w-full max-w-xl gap-1">
<Subagent
name="researcher"
task="Find how the billing service rounds prorated charges"
status="success"
activity="searching"
durationMs={14200}
defaultOpen
toolCalls={[
{
name: "grep",
status: "success",
summary: "Search for “Math.round” in src/billing",
input: { pattern: "Math.round", path: "src/billing" },
output: "src/billing/proration.ts:61\nsrc/billing/invoice.ts:132",
durationMs: 180,
},
{
name: "read_file",
status: "success",
summary: "Read src/billing/proration.ts",
input: { path: "src/billing/proration.ts", lines: "40-80" },
durationMs: 95,
},
]}
result={
<p>
Proration rounds each line with <code className="font-mono text-[13px]">Math.round</code> before summing, so
two half cents can round down together. Rounding once after the sum fixes the failing test.
</p>
}
/>
<Subagent
name="test-runner"
task="Run the billing tests after the fix"
status="running"
activity="working"
activityLabel="Running tests"
toolCalls={[{ name: "run_command", status: "running", summary: "pnpm vitest run src/billing" }]}
/>
</div>
);
}API
| Prop | Type | Default | Description |
|---|---|---|---|
| name | string | — | The subagent's name, in monospace. |
| task | ReactNode | — | What it was asked to do. |
| status | "queued" | "running" | "waiting" | "success" | "error" | "cancelled" | — | Drives the Agent State pill. |
| activity / activityLabel | AgentActivity / string | "working" | The mark and verb while running. |
| toolCalls | (ToolCallCardProps & { id? })[] | — | Its own tool calls, rendered as Tool Call Cards on the rail. |
| result | ReactNode | — | What it returned to the parent agent. |
| error | ReactNode | — | Why it failed; always visible when status is error. |
| durationMs | number | — | Elapsed time, shown once it ends. |
| defaultOpen / open / onOpenChange | boolean / (open) => void | — | Base UI Collapsible open state. |
Accessibility
- The header is a Base UI Collapsible trigger (a button with aria-expanded) whose hit area and focus ring cover the whole row.
- The state pill sits outside the button as a live region, so Running, Waiting for approval, Done, and Failed are announced as they change.
- aria-busy is set while running; tool calls are an ordered list labelled with the subagent's name.
- The panel height animates in 220ms; the marks hold still frames and disclosures are instant with reduced motion.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/agent/subagent.tsxsubagent- Also installs agent-state@0.1.0registry dependency
- Also installs tool-call-card@0.3.0registry dependency
- npm packages: @base-ui/react@^1.9.0React and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/subagent/0.1.0.json.
agent/subagent.tsxShowHide
agent/subagent.tsx
"use client";
import { Collapsible } from "@base-ui/react/collapsible";
import type { ReactNode } from "react";
import { type AgentActivity, type AgentPhase, AgentState } from "./agent-state";
import { ToolCallCard, type ToolCallCardProps } from "./tool-call-card";
function cx(...classes: (string | false | null | undefined)[]) {
return classes.filter(Boolean).join(" ");
}
const ease = "ease-[cubic-bezier(0.23,1,0.32,1)]";
export type SubagentStatus = "queued" | "running" | "waiting" | "success" | "error" | "cancelled";
const phases: Record<SubagentStatus, { phase: AgentPhase; label?: string }> = {
queued: { phase: "idle", label: "Queued" },
running: { phase: "active" },
waiting: { phase: "waiting", label: "Waiting for approval" },
success: { phase: "done", label: "Done" },
error: { phase: "failed", label: "Failed" },
cancelled: { phase: "cancelled", label: "Cancelled" },
};
export interface SubagentToolCall extends ToolCallCardProps {
/** Stable key for the call. Defaults to its position. */
id?: string;
}
export interface SubagentProps extends Omit<Collapsible.Root.Props, "className" | "children"> {
/** The subagent's name, for example `researcher`. */
name: string;
/** What it was asked to do. */
task: ReactNode;
status: SubagentStatus;
/** Which Agent State mark animates while it runs, and the default verb. */
activity?: AgentActivity;
/** Replaces the running verb, e.g. "Reading the docs". */
activityLabel?: string;
/** Its own tool calls, in order, rendered as Tool Call Cards. */
toolCalls?: SubagentToolCall[];
/** What it returned to the parent agent. */
result?: ReactNode;
/** Why it failed. Always visible when the status is error. */
error?: ReactNode;
/** Elapsed time, shown once it ends. */
durationMs?: number;
/** Extra content inside the run, after the tool calls. */
children?: ReactNode;
className?: string;
}
/**
* A nested agent run: its name, task, and live state in a header row, and underneath, on an
* indented hairline rail, its own tool calls and the result it handed back. Collapsible.
*/
export function Subagent({
name,
task,
status,
activity = "working",
activityLabel,
toolCalls = [],
result,
error,
durationMs,
children,
className,
...props
}: SubagentProps) {
const meta = phases[status];
const finished = status === "success" || status === "error" || status === "cancelled";
const calls = toolCalls.length;
return (
<Collapsible.Root
data-status={status}
aria-busy={status === "running" || undefined}
className={cx("@container w-full text-left text-zinc-950 dark:text-white", className)}
{...props}
>
<div className="relative flex flex-wrap items-start gap-x-3 gap-y-1.5 py-2 pr-9 pl-2">
<Collapsible.Trigger
className={cx(
"group flex min-w-0 flex-1 cursor-pointer items-start gap-3 text-left",
// The trigger's hit area and hover tint cover the whole header row.
"before:absolute before:inset-0 before:rounded-lg before:transition-colors before:duration-150 before:ease-out motion-reduce:before:transition-none",
"hover:before:bg-zinc-950/[0.03] dark:hover:before:bg-white/[0.04]",
"outline-none focus-visible:before:outline-2 focus-visible:before:-outline-offset-2 focus-visible:before:outline-sky-500",
)}
>
<span
aria-hidden="true"
className={cx(
"relative mt-px flex size-6 shrink-0 items-center justify-center rounded-full text-zinc-600 dark:text-zinc-300",
"shadow-[inset_0_0_0_1px_rgb(9_9_11/0.1)] dark:shadow-[inset_0_0_0_1px_rgb(255_255_255/0.16)]",
)}
>
<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" className="size-3.5">
<circle cx="5" cy="4.5" r="1.75" />
<circle cx="11" cy="11.5" r="1.75" />
<path d="M5 6.25v2.5c0 1.38 1.12 2.5 2.5 2.5h1.75" />
</svg>
</span>
<span className="relative min-w-0 flex-1">
<span className="flex items-baseline gap-2">
<span className="truncate font-mono text-[13px] leading-6 font-medium">{name}</span>
<span className="shrink-0 text-xs text-zinc-500">
Subagent{calls ? `, ${calls} tool ${calls === 1 ? "call" : "calls"}` : ""}
</span>
</span>
<span className={cx("block text-sm", status === "queued" ? "text-zinc-500" : "text-zinc-600 dark:text-zinc-400")}>{task}</span>
</span>
<svg
aria-hidden="true"
viewBox="0 0 16 16"
className={`absolute top-3.5 right-2.5 size-4 text-zinc-500 transition-transform duration-200 ${ease} group-data-panel-open:rotate-180 motion-reduce:transition-none`}
>
<path d="m4.5 6.25 3.5 3.5 3.5-3.5" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
</svg>
</Collapsible.Trigger>
{/* In a narrow container the state wraps under the task so the name keeps its room. */}
<div className="pointer-events-none relative flex shrink-0 items-center gap-2.5 @max-md:basis-full @max-md:pl-9">
{finished && durationMs != null ? (
<span className={`font-mono text-xs text-zinc-500 tabular-nums transition-opacity duration-300 ${ease} starting:opacity-0 motion-reduce:transition-none`}>
{formatDuration(durationMs)}
</span>
) : null}
<AgentState status size="sm" activity={activity} phase={meta.phase} label={meta.label ?? activityLabel} />
</div>
</div>
{status === "error" && error != null ? (
<p
className={`mt-1 mb-2 ml-11 rounded-lg border border-red-500/35 bg-red-500/[0.08] px-3 py-2 text-sm text-red-700 transition-[opacity,translate] duration-200 ${ease} starting:-translate-y-1 starting:opacity-0 motion-reduce:transition-none dark:text-red-300`}
>
{error}
</p>
) : null}
<Collapsible.Panel
className={cx(
"h-(--collapsible-panel-height) overflow-hidden",
`transition-[height,opacity] duration-220 ${ease} motion-reduce:transition-none`,
"data-starting-style:h-0 data-starting-style:opacity-0",
"data-ending-style:h-0 data-ending-style:opacity-0 data-ending-style:duration-180",
)}
>
<div className="ml-5 border-l border-zinc-950/10 pt-1 pb-2 pl-6 @max-md:pl-3 dark:border-white/10">
{calls ? (
<ol aria-label={`${name} tool calls`} className="grid gap-2">
{toolCalls.map(({ id, ...call }, index) => (
<li key={id ?? index}>
<ToolCallCard {...call} />
</li>
))}
</ol>
) : status === "running" || status === "queued" ? (
<p className="py-1 text-sm text-zinc-500">No tool calls yet</p>
) : null}
{children}
{result != null ? (
<div className={cx(calls || children ? "mt-4" : "", `transition-[opacity,translate] duration-200 ${ease} starting:translate-y-1 starting:opacity-0 motion-reduce:transition-none`)}>
<p className="mb-1 text-xs font-medium text-zinc-500">Result</p>
<div className="text-sm leading-relaxed text-zinc-800 dark:text-zinc-200">{result}</div>
</div>
) : null}
</div>
</Collapsible.Panel>
</Collapsible.Root>
);
}
function formatDuration(ms: number): string {
if (ms < 1000) return `${Math.round(ms)} ms`;
if (ms < 60_000) return `${(ms / 1000).toFixed(1)} s`;
return `${Math.floor(ms / 60_000)}m ${Math.round((ms % 60_000) / 1000)}s`;
}