Skip to content
txbrendan/ui

Agent Inbox

beta

One calm list of background agent tasks, grouped into Needs you, Running, and Done, with filter tabs and live counts. A row opens to its last steps and the action its state needs.

Built from Accordion, Badge, Button, Card, Motion Timing, Skeleton, Spinner, Status Text, Tabs, and Timeline.

Preview

2 need you, 2 running.

Needs you2

Running2

Done1

loading

Loading tasks

empty

0 need you, 0 running.

Tasks you hand to an agent show up here.

narrow container

2 need you, 1 running.

Needs you2

Running1

Install

  1. 1. Add the registry to components.json, once per app. Without it, the shadcn CLI looks up @txbrendan in a public list that txbrendan/ui does not control.

    npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json"

  2. 2. Add the theme, once per app. It replaces your color tokens with ones checked for contrast.

    npx shadcn@latest add @txbrendan/theme

  3. 3. Add the block. It also adds every component it uses. Its own files go in your components folder, and they are yours to edit.

    npx shadcn@latest add @txbrendan/agent-inbox

Use it for

  • Show people the work their agents do while they are away, sorted by who has to act next.
  • Each task is one row: what it is, where it stands, which model runs it, and how long it has taken.
  • Tasks that wait for a yes or no and tasks that stopped both sit under Needs you, where people look first.
  • Give a failed task a short reason, like "API key expired", so people can tell whether Retry will help.
  • Pass elapsed in seconds. Running and waiting rows count on from there, once a second.
  • Without handlers, Approve, Reject, and Retry change the task inside the block. Pass a handler to own the change in your own state.

Avoid it for

  • A queue of more than a few dozen tasks. Use a DataTable with paging and search.
  • A task's full log. Link to it with href, and show the log on its own page.
  • Tasks that finish in a second or two. Show the result where people asked for it.

Props

  • tasks

    One row per task, in order inside each group. ids must be unique. steps are oldest first, and a row shows the last four. href puts an Open link on running and done tasks. A new list, by value, replaces changes made inside the block.

    { id: string; title: string; summary?: string; model: string; status: "waiting" | "running" | "done" | "failed"; elapsed?: number; reason?: string; steps?: { label: string; time?: string }[]; href?: string }[] · default []

  • onApprove

    Approve on a waiting task. Without it, the task moves to Running.

    (task: AgentTask) => void

  • onReject

    Reject on a waiting task. Without it, the task fails with "Rejected" as its reason.

    (task: AgentTask) => void

  • onRetry

    Retry on a failed task. Without it, the task moves to Running and its clock starts over.

    (task: AgentTask) => void

  • onOpen

    Shows Open on running and done tasks that have no href.

    (task: AgentTask) => void

  • loading

    Shows placeholder rows and hides the counts.

    boolean · default false

  • loadingText

    What the status line tells screen readers while loading.

    string · default "Loading tasks"

  • emptyText

    Shown when there are no tasks and nothing is loading.

    string · default "No agent tasks yet."

  • label

    Names the filter tabs for screen readers.

    string · default "Agent tasks"

  • className

    Extra classes on the outer div, which holds the container query.

    string

Accessibility

  • The filters are tabs. Arrow keys move between them, and each tab says its count.
  • Each row is a button inside a heading, with aria-expanded. Enter or Space opens it to the last steps and the actions.
  • Each group is a labeled group in the All tab, so screen readers say Needs you, Running, or Done.
  • Status is words with a color, like Waiting for you or Failed: and a reason. Color never carries it alone.
  • After Approve, Reject, or Retry, focus moves to the row in its new place. When the open filter hides it, focus goes to the tab.
  • One status line outside the lists reads out each change: which task, what happened, and the new counts. The clocks never speak.
  • With reduced motion, rows take their new place at once, and the running spinner stays still.

Examples

Background tasks

<AgentInbox
  tasks={[
    {
      id: "invoices",
      title: "Send March invoices",
      summary: "Drafted 38 invoices. Ready to email them to clients.",
      model: "Opus 5.5",
      status: "waiting",
      elapsed: 412,
      steps: [
        { label: "Drafted 38 invoices", time: "4m ago" },
        { label: "Wants to email 38 clients", time: "1m ago" },
      ],
    },
    { id: "tests", title: "Find the flaky checkout test", model: "Sonnet 5.5", status: "running", elapsed: 221, href: "/runs/tests" },
    { id: "index", title: "Rebuild the search index", model: "Haiku 5.5", status: "failed", reason: "docs server timed out", elapsed: 534 },
  ]}
/>

Your own state owns each change

"use client";

function TaskInbox() {
  const { data: tasks } = useTasks();
  return (
    <AgentInbox
      tasks={tasks ?? []}
      loading={tasks === undefined}
      onApprove={(task) => approveTask(task.id)}
      onReject={(task) => rejectTask(task.id)}
      onRetry={(task) => retryTask(task.id)}
      onOpen={(task) => openTask(task.id)}
    />
  );
}

With nothing to show yet

<AgentInbox tasks={[]} emptyText="Tasks you hand to an agent show up here." />