Monitoring your agents

Monitoring your agents is different from watching a single live session or checking in on one task. This guide is about fleet health: are all your agents picking up work, has anything fallen into an unexpected state, are your capabilities configured correctly so tasks can actually be staffed? For watching one specific session in real time, see Following a live agent session. For tracking individual tasks, see Finding and tracking your work.

The Agents page

Open Agents in the sidebar under Set up. The page lists every agent template in your workspace (including templates inherited from a parent group, shown with a badge).

Template list columns:

Column	What it shows
Name	The agent’s display name. A disabled badge appears here when the agent has been paused.
Last used	When the agent last took a meaningful action (a task claim, a comment, a status change, a message). Shows recently used (a green indicator) if the activity was very recent; otherwise shows a timestamp.
Operator	The human member responsible for this agent template.
Role	The role label set on the agent (for example, ic or leader).
Capabilities	The capability labels declared on the agent template itself (for example, model:sonnet, go) — set with ch agent create --cap and editable afterward. These labels are a soft signal used to rank agents when the engine auto-staffs unassigned work; they are not what determines whether a workflow stage can actually run on this agent. That’s decided separately, by the agent’s launch config — see Capability gap warning below.

Capability gap warning

For the full rundown of what a capability label is and the different rules that apply to agent skills, launch configs, and stage requirements, see Capabilities.

If a workflow stage’s required capability isn’t covered by any template’s labels in the list above, a warning callout appears at the top of the page:

Capability gap: your workflow stages require <cap> — but no agent template below provides it. Tasks reaching those stages park unstaffable (no capable template).

Treat this as an early heads-up, not the authoritative check. It compares stage requirements against the template-level capability labels shown in the Capabilities column — but the engine’s actual staffing decision looks at each agent’s launch config instead: a stage only ever runs on a config whose own capabilities cover it (see Capabilities and routing in Agents and the CLI). Because a template’s labels and its launch config’s capabilities are set independently, this callout can occasionally miss a real gap, or flag one a launch config has already closed.

If a task is genuinely stuck on a stage, confirm the cause in Why isn’t my task moving?, then close a real gap the way that actually matters — give the agent’s launch config the missing capability:

ch agent config set <agent-id> --harness <h> --cap <capability>

Pausing and resuming an agent

You can temporarily stop an agent from picking up new work without affecting sessions that are already running. To do this, click Disable in the row action on the right side of the agent’s row on the Agents page. The agent’s row gains a disabled badge. Any sessions already in progress for that agent continue to completion; only new task assignments are blocked.

To re-enable the agent and let it pick up work again, click Enable on the same row.

There is no CLI command for this action — it is a web app action only.

Workload snapshots from the CLI

ch agent workload gives you a point-in-time workload snapshot for an agent or a team of agents.

Your own workload (when running as an agent or a human member):

ch agent workload

One specific agent — pass its display name or its full ID:

ch agent workload Builder

All agents in a team:

ch agent workload --team <teamId>

Add --sort <key> to control the team list order. Valid sort keys: -inProgress (default, highest first), inProgress (lowest first), -pending, pending, oldestInProgress, -unreadDMs.

Workload columns:

Column	What it shows
IN_PROGRESS	Tasks this agent is currently working — actively in a non-terminal stage.
PENDING	Tasks assigned to this agent but not yet started.
UNREAD_DMS	Direct messages waiting in the agent’s inbox.
OLDEST_IP	Age of the oldest in-progress task (e.g. 2h, 3d). A dash means none in progress.

A high PENDING count with a low IN_PROGRESS count often means the agent’s device is offline or the agent has no approved device assignment. A large OLDEST_IP value is worth investigating — see Why isn’t my task moving? for the most common causes.

Per-agent event feed

ch activity agent <agent> streams the event history for one agent — pass its display name or its full ID:

ch activity agent Builder

This prints the most recent events newest-first: status changes, task claims, comments, messages, and other actions that agent has taken. Use it to quickly confirm an agent is active, or to trace what it has been doing. For the full flag reference — lookback windows, tailing with --cursor and --wait, filtering by type or subject — see Activity feeds.

When you need the full ID instead of the name: mostly you don’t — the display name works anywhere these commands take an agent. Reach for the ID for scripting, or when a name is ambiguous (ch reports every match rather than guessing — see Using the ch CLI). Open the Agents page and click the agent’s row to see the ID at the top of its detail page, or run ch agent list from the CLI, which prints each agent’s ID next to its display name. (Running ch agent workload with no argument shows your own AGENT_ID line, but only for the agent you’re signed in as.)

Quality metrics: first-pass rate

First-pass rate tells you how often your agents get it right on the first attempt. It is the share of completed tasks that reached done without being sent back to the build stage for rework — reported separately for each combination of AI model and workflow stage.

A high first-pass rate in a row means that model, running that stage, rarely needed a second attempt. A low rate is worth investigating: are the tasks well-specified? Is the model a good fit for that kind of work?

Run ch quality first-pass-rate (alias fpr) to see the breakdown for your workspace:

ch quality first-pass-rate

Output columns:

Column	What it shows
MODEL	The AI model that ran the stage.
STAGE	The workflow stage (for example, code or review).
COMPLETED	Total tasks that finished this stage in the window.
FIRST-PASS	Tasks that completed this stage without any rework.
RATE	First-pass count divided by completed count, as a percentage.

The default window covers the last 90 days. Change it with --since:

ch quality first-pass-rate --since 30d

--since accepts a relative duration (Nd, Nh, or Nm for days, hours, and minutes) or a full RFC 3339 timestamp — the same grammar as ch costs --since:

ch quality first-pass-rate --since 2026-01-01T00:00:00Z

To scope the report to a specific workspace, pass its UUID as the first argument:

ch quality first-pass-rate <workspaceId>

Without a workspace ID the command defaults to CH_WORKSPACE_ID.

Add --json to receive the raw data instead of the formatted table — useful for scripting or feeding a dashboard:

ch quality first-pass-rate --json

First-pass rate is one half of the review picture — for the other half (review latency, how often work bounces back, and what review costs), see Review debt.

---

For creating and configuring agent templates, see Agents and the CLI. To watch a specific session in real time, see Following a live agent session. To understand why a task has stalled, see Why isn’t my task moving?. To assign tasks to specific agents, see Assigning and claiming work. For the full task-tracking picture — filters, the board, and the activity feed — see Finding and tracking your work.

Related guides

• Managing your devices — device health, capacity, and troubleshooting
• Running the device server as a service — run device-server as a persistent background service
• Updating the CLI — keep the CLI and device server binary current