Skip to content
Shaken UI
Sign in

Subagent

Save

A 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 subagent

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add subagent --dry-run

Usage

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

PropTypeDefaultDescription
namestring—The subagent's name, in monospace.
taskReactNode—What it was asked to do.
status"queued" | "running" | "waiting" | "success" | "error" | "cancelled"—Drives the Agent State pill.
activity / activityLabelAgentActivity / string"working"The mark and verb while running.
toolCalls(ToolCallCardProps & { id? })[]—Its own tool calls, rendered as Tool Call Cards on the rail.
resultReactNode—What it returned to the parent agent.
errorReactNode—Why it failed; always visible when status is error.
durationMsnumber—Elapsed time, shown once it ends.
defaultOpen / open / onOpenChangeboolean / (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.tsxShow
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`;
}