Agent Monitor

A live board of the agents you have running: what each one is doing right now, its tasks, a trace of its tool calls and the sub-agents it started.

1Working0Needs you0Done0Failed

koala-site

koala-api

Refresh the pricing page

koala-site

Working

Tasks

0/4

Read the current page
In progress
Split the work into two agents
Not started
Move the plans to the new cards
Not started
Run the checks
Not started

Last minute

ReadEditRunSearchAgentOther

Log

Reading pricing/page.tsx

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

# Add this component (its dependencies come along)
npx koalaui-cli@latest add agent-monitor

Usage#

The monitor draws what you give it and fetches nothing, so it works with any agent runtime. Keep your runs in state, from polling, a socket or a stream, and map each one to a row and a panel.

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Get the code

Have a license? Unlock it here

Anatomy#

import {
  AgentMonitor,
  AgentMonitorSummary,
  AgentMonitorCount,
  AgentList,
  AgentGroup,
  AgentGroupLabel,
  AgentRow,
  AgentRowHead,
  AgentName,
  AgentElapsed,
  AgentActivity,
  AgentTrace,
  AgentDetail,
  AgentDetailHeader,
  AgentDetailHeading,
  AgentDetailTitle,
  AgentDetailDescription,
  AgentStatusBadge,
  AgentSection,
  AgentSectionTitle,
  AgentProgress,
  AgentTasks,
  AgentTraceLegend,
  AgentLog,
  AgentLogItem,
  AgentEmpty,
} from "@/components/ui/agent-monitor"

States#

A row carries one of five states. Only a working agent pings and only one that needs you blinks, so the board stays calm and the eye goes where it is needed.

API reference#

AgentMonitor

The board and the context every part reads, built on Radix Tabs: arrow keys walk the rows and each row owns a detail panel. Takes value, defaultValue and onValueChange. Every part accepts className, merged last.

Prop	Type	Default	Description
variant	"card" \| "plain"	"card"	A framed surface, or no chrome for a full page.
density	"comfortable" \| "compact"	-	Row and panel spacing. Reads `DensityProvider` when unset.

AgentMonitorCount

One figure in AgentMonitorSummary. Children replace the status label.

Prop	Type	Default	Description
status*	"working" \| "waiting" \| "idle" \| "done" \| "failed"	-	Sets the dot and the default label.
count*	number	-	The figure, in tabular numerals.

AgentRow

One agent in the list, and the tab that opens its AgentDetail. Compose AgentRowHead, AgentActivity and AgentTrace inside it.

Prop	Type	Default	Description
value*	string	-	Matches the `AgentDetail` it opens.
status	"working" \| "waiting" \| "idle" \| "done" \| "failed"	"idle"	Drives the mark: a pinging dot, a blinking dot, a check or a warning.
depth	number	0	Indents a sub-agent under the agent that started it.
statusLabel	string	-	The status as read by a screen reader. Use it to translate.

AgentActivity

The one line that says what the agent is on. When the text changes the old line leaves and the new one arrives in place.

Prop	Type	Default	Description
children*	string	-	The current activity.

AgentElapsed

A running timer in tabular numerals. All timers on a page share one clock.

Prop	Type	Default	Description
since*	number	-	Start time in epoch milliseconds.
until	number	-	Stops the timer at this time.

AgentProgress

Tasks finished, as pips and a count.

Prop	Type	Default	Description
done*	number	-	Finished tasks.
total*	number	-	All tasks. One pip each.

AgentTrace

A strip of the agent's tool calls over time, coloured by kind. Open calls grow until they get an end.

Prop	Type	Default	Description
spans*	readonly AgentSpan[]	-	`{ id, kind, start, end?, failed? }`, with times in epoch milliseconds.
window	number	600000	How far back the strip reaches, in milliseconds.
size	"sm" \| "md"	"sm"	The thin strip for a row, or the taller one for a panel.

AgentTraceLegend

Names the colours of AgentTrace.

Prop	Type	Default	Description
labels	Partial<Record<AgentSpanKind, string>>	-	Replaces any label, to translate or rename.

AgentStatusBadge

The status as a Badge. Children replace the label.

Prop	Type	Default	Description
status*	"working" \| "waiting" \| "idle" \| "done" \| "failed"	-	Sets the colour and the default label.

AgentTasks

The agent's to-dos, drawn with the steps of Plan.

Prop	Type	Default	Description
tasks*	readonly AgentTask[]	-	`{ id, title, status }`, with the status of a `PlanStep`.

AgentLogItem

One line of AgentLog.

Prop	Type	Default	Description
kind	"read" \| "edit" \| "run" \| "search" \| "agent" \| "other"	"other"	The colour of its dot, the same as in the trace.
failed	boolean	false	Marks the call as failed.
time	ReactNode	-	Shown at the end of the line.

FAQ#

From you. The monitor has no connection of its own: pass it the state of your runs from whatever your agents report to, and it redraws when that state changes.