| # Agent Process Dashboard Original MVP Plan |
|
|
| Note: the original MVP was read-only. The current app keeps read-only scanning |
| but now also supports explicit, confirmed `SIGTERM`/`SIGKILL` actions for fresh |
| dry-run candidates only. |
|
|
| Original direction: standalone GTK desktop app. The MVP was read-only plus |
| dry-run candidate reporting only, with no kill execution, no generated kill |
| command, no localhost server, and no network port. `/proc` is the primary |
| sampler. |
|
|
| ## Summary |
|
|
| Build a new standalone GTK app in: |
|
|
| `/home/smlflg/Projekte/agent-process-dashboard` |
|
|
| The app monitors Samuel's current-user Linux process tree, classifies |
| agent/MCP/bridge processes, shows parent/child fanout, flags stale candidates, |
| and reports what a cleanup would target without executing it. |
|
|
| Superseded direction: the previous FastAPI/static web UI plan is replaced. Keep |
| its useful `/proc`, PID identity, classification, tree/group, and risk ideas; |
| remove localhost server, web frontend, and systemd daemon work from the MVP. |
|
|
| ## Key Changes |
|
|
| - Python package: `agent_process_dashboard`. |
| - UI: GTK3/PyGObject desktop window. |
| - Core sampler: direct `/proc` reads, no `psutil` dependency in the MVP. |
| - Process identity: `boot_id:pid:start_time_ticks:uid`. |
| - Safety: |
| - No `SIGTERM`, `SIGKILL`, renice, restart, or config mutation. |
| - No `/proc/<pid>/environ` reads. |
| - No executable cleanup command is printed. |
| - Dry-run output is only candidate PIDs, identity keys, reasons, and |
| exclusions. |
| |
| ## Implementation Tasks |
|
|
| 1. Scaffold project files: |
| - `pyproject.toml` |
| - `README.md` |
| - `src/agent_process_dashboard/` |
| - `tests/` |
|
|
| 2. Build testable core modules: |
| - `procfs.py`: read `/proc`, parse stat/status/cmdline/statm/cgroup, handle |
| disappearing PIDs. |
| - `sanitize.py`: mask secrets in argv before display. |
| - `classifier.py`: classify Claude, Codex, Hermes, opencode, Gemini, MCP |
| servers, bridges, wrappers, terminals, editors, browsers, and unknowns. |
| - `tree.py`: build parent/child trees and launch groups. |
| - `risk.py`: compute fanout, bridge, stale, and global warning levels. |
| - `dryrun.py`: generate read-only cleanup candidate reports. |
| - `snapshot.py`: orchestrate sampler, classifier, tree, risk, and dry-run. |
| |
| 3. Build GTK UI: |
| - Header KPIs: agent roots, MCP/bridges, max fanout, stale candidates, CPU |
| hot, last scan. |
| - Left: agent/root group list. |
| - Center: process tree using `Gtk.TreeStore`. |
| - Right: selected process details. |
| - Bottom: dry-run candidate report. |
| - Filters: Agent, MCP, Bridge, Stale, High Fanout. |
| - Poll active snapshots every 2 seconds, idle snapshots every 5-10 seconds. |
| |
| 4. Risk defaults: |
| - Per group child count `>= 20`: warn. |
| - Per group child count `>= 50`: critical. |
| - Per group bridge count `>= 6`: warn. |
| - Per group bridge count `>= 12`: critical. |
| - Global MCP/bridge count `>= 20`: warn. |
| - Global MCP/bridge count `>= 50`: critical. |
| - Global agent-related count `>= 30`: warn. |
| - Global agent-related count `>= 70`: critical. |
| - Bridge age `> 6h`: stale candidate. |
| - Bridge age `> 24h`: strong stale candidate. |
| - CPU idleness alone never makes a bridge stale. |
|
|
| ## Test Plan |
|
|
| - Unit tests: |
| - `/proc/<pid>/stat` parser handles spaces and parentheses. |
| - PID reuse produces different `process_key`. |
| - Missing processes during scan do not fail a snapshot. |
| - Cmdline masking handles flags, `--flag=value`, env-style args, URLs, and |
| common token prefixes. |
| - Classifier avoids false positives from paths or incidental words. |
| - Parent links are rejected when parent identity is absent/unstable. |
| - Healthy idle MCP bridge is not marked stale. |
| - Dry-run performs no mutation and returns no executable kill command. |
| |
| - Integration smoke: |
| - Spawn a shell with a child process and verify tree grouping. |
| - Verify the app spawns no MCP/bridge children. |
| - Verify no port is opened. |
| - Verify no `/proc/<pid>/environ` reads exist in the code. |
| - Target RSS budget: below about 300 MB. |
|
|
