Resource monitor for Claude Code and Codex

English · 繁體中文 · 简体中文

---

Agentinel = Agent + Sentinel. A cross-platform (Windows + macOS) desktop app that watches the resource footprint of the many AI agents you run at once — and gives you AI advice on what to clean up.

It does what a normal Task Manager can't: identifies agent processes, groups them by project, tracks parent/child trees, detects leaks / zombies / duplicate sessions, and explains it all using your own Claude / Codex / Gemini / OpenCode CLI — no extra API key. Read-only by design: every kill / suspend / cleanup runs only after you click.

Screenshots

Full dashboard — live processes, a system-health strip, and AI anomaly detection.

Menu-bar mini panel — a glance from the tray: live RAM/CPU, the AI-flagged leak, and your top agents.

Highlights

• One tray app, two windows. Launch agentinel.py and it lives in the system tray: a resident mini panel for glances, and the full dashboard opened on demand. Both share one process and one scanner. Closing the dashboard just hides it (state preserved — no AI re-run); quit only from the tray.
• Modern, frameless UI. Custom title bar with native OS dragging (no lag), light/dark themes, theme-aware logo, sidebar navigation and a system-health hero strip.
• Multilingual (UI + AI). English-primary, switch to 繁體中文 / 简体中文 anytime. The AI answers in whatever language you pick (one call + a language directive — no wasted tokens), shared between both windows.
• Agent identification. Claude Code, Codex, Gemini CLI, OpenCode, Hermes, TermHive, MCP servers, dev servers (vite/next/remix…), Ollama, Claude Desktop — auto-classified. argv[0] fallback recognizes agents even when they rewrite their process title (e.g. Claude Code showing a version number like 2.1.152).
• Whole-system view. Scans every process by default, not just agents — Chrome / Slack / Docker / forgotten CLIs included. Heavy non-agents (≥200 MB) carry their full command line so the AI can identify them without asking you to run ps.
• Idle detection. Tracks "time since last CPU activity" per process — a far better zombie signal than uptime alone (long-running ≠ abandoned).
• Process tree + AI reading. Tree view tucks an agent's spawned shells (cmd / bash / node / bun) underneath; ask the AI to read each child's command line and explain the pile in plain language.
• Two-tier findings. A rule engine (free, offline, every 5s) flags leaks, idle zombies, duplicate sessions, orphans, memory pressure. An AI assessment (decoupled cadence — manual or chosen interval, never tied to refresh) re-judges them with proper context, and a process-level cache means the two windows never run a duplicate analysis.
• Conversational AI. Open a chat about a single process, a whole tree, or the system. Auto-detects claude / codex / gemini / opencode with fallback (ENGINES dispatch table in agent_monitor/ai.py — add an engine in one line).
• 💾 Disk module. Fast hotspot scan (HF / Ollama / Docker / pip / npm… with reclaim estimate + 7-day growth) plus a full deep scan that walks the whole drive to surface the biggest folders on any machine.
• 🤖 Cleanup plan. The AI scans RAM + disk and proposes a checklist (reclaim measured, AI only judges risk) — nothing runs until you tick it. The AI may only use a set of safe action blocks (purge-cache / docker-prune / kill / delete-path with a path allow-list…), never arbitrary commands.
• CLI + AI Skill. A read-only CLI (agentinel scan --json / advise / doctor, ~12 MB, no WebView) plus a ready-made skill for Claude Code and Codex — so an agent can check your machine and advise on demand. See CLI and Use as an AI Skill.

Install

pip install -r requirements.txt

Python 3.9+. Windows needs the WebView2 Runtime (built into Win11); macOS uses the built-in WKWebView.

Run

python agentinel.py     # ⭐ recommended — tray icon + mini panel + dashboard (one process)
python app.py           # full dashboard only
python mini.py          # mini tray panel only

From the tray: left-click the icon to show/hide the mini panel, "Open full dashboard" to open the main window, "Quit" to exit.

CLI

No GUI, ~12 MB (vs ~250 MB for the GUI) — great for terminals, scripts and AI skills. It talks to the same Monitor + AI engines as the app.

./agentinel scan                  # whole-system top 20, text table
./agentinel scan --agents-only    # agents only
./agentinel scan --top 50         # text table, top 50
./agentinel scan --json | jq      # JSON for scripts / skills / MCP
./agentinel advise                # run the AI, render markdown advice
./agentinel advise --engine codex # switch engine (claude|codex|gemini|opencode)
./agentinel doctor                # show detected AI CLIs + fallback order

(or python -m agent_monitor <subcommand> — the ./agentinel wrapper just auto-finds a sibling .venv.)

Use as an AI Skill (Claude Code / Codex)

The CLI is built to be driven by another agent. This repo ships a ready-made skill so Claude Code or Codex can answer "what's eating my RAM / any zombie agents / what can I clean up?" by running Agentinel and interpreting the result — same skill, both tools.

• Claude Code — .claude/skills/agentinel/SKILL.md. Auto-available inside this repo. To use it in any project, copy that folder to ~/.claude/skills/agentinel/.
• Codex — .codex/prompts/agentinel.md. Copy it to ~/.codex/prompts/agentinel.md and invoke it with /agentinel.

Both wrap the same read-only CLI (scan --json / advise); the skill never kills or deletes — destructive actions stay in the GUI's confirm-to-run flow.

Architecture

agentinel.py            ⭐ unified launcher — one process owns the tray + mini + dashboard
app.py                  full-dashboard window + JS↔Python bridge (js_api) + window controls
mini.py                 tray / menu-bar mini panel (pystray icon + frameless popover)
agentinel               bash wrapper for the CLI (auto-finds .venv)
.claude/skills/agentinel/SKILL.md   AI skill for Claude Code (read-only resource checks)
.codex/prompts/agentinel.md         same guidance as a /agentinel prompt for Codex
agent_monitor/
  __main__.py           enables `python -m agent_monitor` (CLI)
  cli.py                CLI subcommands: scan / advise / doctor (rich rendering)
  engine.py             detection, classification, project attribution, idle tracking,
                        process trees, rule engine, snapshots (thread-safe Monitor)
  actions.py            kill / kill-tree / suspend / resume (explicit calls only)
  ai.py                 ENGINES dispatch (claude/codex/gemini/opencode); chat / assess /
                        tree reading / plan review; output-language directive (EN/繁/简)
  disk.py               disk hotspot scan + growth history + full deep scan
  plan.py               cleanup plan: candidate actions + safe action blocks + executor
ui/
  index.html  app.js    full dashboard (sidebar, health strip, processes/disk/plan, drawer)
  mini.html             mini panel (live tiles, AI alerts, inline Q&A)
  style.css             design system (light/dark)
  logo-*.png  icon*.png  banner.png   branding assets
data/                   runtime data (lang.txt, disk_history.json…) — gitignored

Debug

Launch with AGENTMON_DEBUG=1 to open the WebView devtools.

Roadmap

• Unified single-process tray app (mini panel + dashboard, shared Monitor)
• SaaS dashboard redesign + light/dark + frameless window with native drag
• Multilingual UI + AI output (EN / 繁體中文 / 简体中文)
• Disk module (hotspots + full deep scan + growth) and cleanup-plan engine
• AI conversation + decoupled AI findings assessment
• Resident janitor: periodic scan + notify on RAM/disk threshold breach
• UI-tunable rule thresholds, persisted AI assessments
• Single-file packaging (PyInstaller); later evaluate a Tauri/Rust rewrite