microagent stats

Last updated: 2026-08-15

microagent stats <name> [--follow] [--state-dir <dir>]

stats reports CPU, memory, and I/O for a running workspace, sampled from the host view of the backing VM monitor process (similar to how docker stats reads container resource accounting). CPU percent is measured across a short interval and can exceed 100% for a multi-vCPU workspace.

By default stats prints one sample. With --follow (-f) it streams samples about once a second until the workspace stops or you interrupt with Ctrl-C. With the global --json flag a single sample is returned as a JSON object; --follow is not supported with JSON output.

Follow mode may show one delayed indicator while acquiring its first sample. It stops before that sample is written; later samples are the only recurring output.

The workspace must be running; stats on a stopped workspace is an error.

Examples

Take one sample:

microagent stats research

pid=48213  cpu=4.5%  mem=256.0 MiB  io_read=12.0 MiB  io_write=3.5 MiB

Get the structured sample:

microagent --json stats research

{
  "pid": 48213,
  "cpuPercent": 4.5,
  "memoryBytes": 268435456,
  "ioReadBytes": 12582912,
  "ioWriteBytes": 3670016,
  "sampledAt": "2026-06-01T20:30:00Z"
}

cpuPercent is measured across a short interval and can exceed 100 for multi-vCPU workspaces. ioReadBytes/ioWriteBytes are present only where the host exposes per-process I/O accounting (Linux); on macOS the fields are absent from the JSON and the text line omits io_read/io_write.

Flags

Add --follow for a live stream instead of one sample.

Flag	Description
--follow, -f	Stream samples until the workspace stops or you interrupt
--state-dir <dir>	State directory holding the workspace record (default ~/.microagent/)

See global flags for --output/--json.

Exit status

stats exits 0 when a sample is taken; nonzero when the workspace cannot be found or is not running.

Related

• perf - boot and footprint benchmarking
• status - state and readiness