← Blog May 18, 2026

# A built-in process monitor for your terminal trees

The fan spins up. One of a dozen agents is pinning a core — but which one? Instead of dropping to `htop` and matching PIDs by hand, we built a process monitor that knows which session owns each process, and exposes it over MCP, over HTTP, and as a self-contained dashboard.

## "Something is eating my CPU"

Running many agents in parallel has a failure mode: one of them goes off the rails — a runaway test loop, a dev server stuck rebuilding, a model thrashing — and the only outward sign is the fan. The system process monitor shows you a list of PIDs and percentages, but it doesn't know that PID 48211 is the agent in your auth-refactor worktree. You're left correlating process trees against terminals by hand, which is exactly the kind of bookkeeping a session orchestrator should do for you.

## CPU and memory, attributed to sessions

TUICommander already tracks which PTY belongs to which session, so it already knows the process-tree roots. The monitor walks those trees and, for every PID, reports resident memory (RSS) and CPU percent — each row tagged with the session it belongs to. On Unix it batches a single `ps -o pid,rss,%cpu` query across all the PIDs at once rather than stat-ing each process individually; on Windows it queries each process's working-set size through the platform API. The output is a flat list of `{ session_id, name, pid, rss_kb, cpu_pct }` — TUIC itself included, so you can see the app's own footprint alongside its children.

## Three ways to read it

The same data is exposed through three surfaces, because the question gets asked in three different contexts:

- Over MCP. The session tool gained a `process_stats` action. An agent — or another agent orchestrating TUIC — can ask "what's the resource picture right now?" and get structured JSON back, which is exactly what you want when something is diagnosing itself.
- Over HTTP. `GET /process/stats` returns the same JSON for scripts, dashboards, or a quick `curl` when you're already in a terminal.
- As a dashboard. `GET /process/monitor` serves a self-contained HTML page — process, PID, session, RSS, CPU in a sortable table — with no build step and no external assets. Open it in a browser tab or pin it as a TUIC panel.

## Why a self-contained page

The dashboard is one HTML file that fetches `/process/stats` and renders the table client-side. No bundler, no framework, no asset pipeline. That's deliberate: a diagnostic tool you reach for when things are misbehaving must not itself depend on a healthy build or a running dev server. It has to work in the degraded state you're trying to debug. A single static page served by the same Rust process that has the data is about as robust as it gets.

## What's next

Point-in-time numbers answer "what's hot now"; the natural next step is "what got hot, and when". The data the monitor already collects is the right input for trend lines and for the always-on diagnostics that watch for FD and thread growth — turning a manual "why is the fan on?" check into something that notices on its own and points straight at the session responsible.