Hugging Face's logo

smlflg
/
agent-process-dashboard

Model card Files
xet
 Community
agent-process-dashboard / IMPLEMENTATION_PLAN.md
smlflg's picture
smlflg
Initial public upload from Projekte/agent-process-dashboard
06357e7 verified
preview code
|
Raw History Blame Contribute Delete
4.02 kB

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.