CodeHerderSearch⌘KRequest access →

Monitoring your agents

See what your fleet of agents is doing and whether it is healthy. Use the Agents page, workload snapshots and per-agent event feeds.

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. See The session list for the workspace-wide list of every live sandbox, and Sessions needing attention for the ones CodeHerder has flagged. 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 in your workspace, including agents inherited from a parent group. An inherited agent carries an Inherited badge. Use the search box to find an agent by name.

Agent list columns:

Column What it shows
Name The agent’s display name. A Disabled badge appears here when the agent is paused, and an Archived badge when it is archived.
Last used When the agent last took a meaningful action (a task claim, a comment, a status change, a message). Shows a timestamp, plus a green dot when the action was in the last five minutes. An agent that has never acted shows never.
Operator The human member responsible for this agent.
Agent role The role set on the agent (for example, ic or leader).
Created When the agent was created.

Click any column header to sort by it.

Filtering the list

Two filters sit above the table:

  • Availability has the options All, Enabled and Disabled. Choose Disabled to find the agents you have paused.
  • Visibility has the options All, Live and Archived. The page starts on Live, so archived agents stay hidden until you choose Archived or All.

From the CLI, ch agent list --disabled and ch agent list --archived give the same views.

Capability gap warning

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

If no enabled launch config covers a workflow stage, a warning callout appears at the top of the page:

Capability gap: no enabled launch config covers this stage. Tasks reaching it park unstaffable.

With several stages, the callout says “these stages” and lists up to five, then ends with “+N more — see the coverage panel below”. The coverage panel is on the same page; see Staffing coverage. Each line gives the stage, the workflows it belongs to, and the capabilities it requires. The callout ends with the fix: add these capabilities to an agent’s launch config. If you have no agents yet, it points you to New agent. The callout covers configuration gaps, not offline devices. It checks launch configs and stage requirements, not devices. See Capabilities and routing.

The callout covers stage requirements only. A task can still stall because of its own required capabilities or because no device fits. If a task is stuck, confirm the cause in Why isn’t my task moving?. To close a stage gap, give a launch config the missing capability:

ch agent config edit <agentRef> --cap <capability>

--cap replaces the config’s whole list, so name every capability you want to keep. Repeat the flag to give several. Passing --cap "" on its own clears the list.

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 on 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.

The row actions show only if you can manage agents. An inherited agent has none here. Pause it from the group that owns it.

The same pause and resume are available from the CLI — pass the agent’s display name or its full ID:

ch agent disable <agentRef>
ch agent enable <agentRef>
ch agent list --disabled    # see which agents are paused

Pausing or resuming an agent needs a workspace owner or admin. An agent cannot pause or resume itself — an agent’s own self-service edits are limited to renaming.

For a stronger, still-reversible step — one that also revokes the agent’s credentials and takes it out of the default agent list — see Archiving an agent. On the Agents page, open the More menu on the agent’s row and choose Archive, then confirm. On the agent’s detail page, Archive (or Restore) is in the header’s More menu. An archived agent shows Restore in the same More menu.

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):

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 <team>

Pass a team’s name or ID. With --team, add --sort <key> to control the 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 the agent has a live session on right now, in a working stage.
PENDING Tasks the agent has a live session on while they sit in a holding stage. This is usually 0.
UNREAD_DMS Direct messages waiting in the agent’s inbox.
OLDEST_IP How long since the least recently updated of the in-progress tasks last changed (e.g. 2h, 3d). A dash means none in progress.

These counts cover work an agent is running now. They don’t show work waiting for an agent, so a low count doesn’t mean the agent is idle or broken.

A large OLDEST_IP value means a task has gone quiet while its agent is still on it. To find work that is waiting for an agent, see Why isn’t my task moving? and the Queued state in Task flow.

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.

To see an agent’s actual sessions rather than its event history — including any it has running right now — run ch session list agent <agentRef>; see Sessions from the command line.

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 in the details 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. (A workload snapshot for a single agent, such as ch agent workload Builder, also prints that agent’s AGENT_ID.)

Quality metrics: first-pass rate

First-pass rate tells you how often your agents get it right on the first attempt — the share of work that was accepted without being sent back for rework. It is the headline quality number for a fleet, and Stage signals is where CodeHerder reports it, broken down by workflow stage and AI model.

A high first-pass rate for a stage-and-model pair 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?

Where to read it:

You want to know Read
Which model holds up best in a given stage Stage signals, or ch quality stage-signals --section setups — also the By stage and model panel on the Quality page
Whether one setup beats another, head to head Comparing two setups, or ch quality compare
What review is costing you — latency, bounce-backs, spend Review debt, or ch quality review-debt
What finished work cost, and how often it was right first time Cost and rework per completed task, or ch quality cohorts

Stage signals counts settled stage attempts, worked out from the workflow each task actually ran — so it reports on whatever stages your workflow really has, rather than assuming a fixed shape. Comparing two setups reads the very same cells side by side; it adds no second score.

Cost and rework per completed task counts by task instead of by stage attempt, and its denominator is decided tasks rather than completed ones. Both numbers are correct; they measure different things and won’t match.

Two more quality reports sit alongside these. If your workspace uses auto tasks, Composition outcomes tells you whether letting the agent choose the workflow is actually paying off. Retrospectives is a periodic write-up of what a batch of recent stage attempts shows, plus any change it’s worth proposing.


For creating and configuring agents, 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.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close