---
name: "Bot htop command with live-updating process dashboard"
---

# Story 298: Bot htop command with live-updating process dashboard

## User Story

As a project owner in a Matrix room, I want to type "{bot_name} htop" and see a live-updating dashboard of system load and agent processes, so that I can monitor resource usage without needing terminal access.

## Acceptance Criteria

- [ ] '{bot_name} htop' sends an initial status message showing load average and per-agent process info (CPU, memory, story assignment)
- [ ] Message is edited every 5 seconds with updated stats
- [ ] Only shows processes related to the project (agent PIDs and their child process trees)
- [ ] '{bot_name} htop stop' stops the live updating and sends a final 'monitoring stopped' edit
- [ ] Works regardless of what language/toolchain the agents are using (monitors by PID tree, not by process name)
- [ ] Uses Matrix message editing (replacement events) to update in place
- [ ] Only one htop session per room at a time — a second '{bot_name} htop' stops the existing session and starts a fresh one
- [ ] Auto-stops after 5 minutes by default to prevent runaway editing
- [ ] Optional timeout override: '{bot_name} htop 10m' to set a custom duration

## Out of Scope

- TBD
