Agentinel

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](#cli) and [Use as an AI Skill](#use-as-an-ai-skill-claude-code--codex).

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 — 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](.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](.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

• [x] Unified single-process tray app (mini panel + dashboard, shared Monitor)
• [x] SaaS dashboard redesign + light/dark + frameless window with native drag
• [x] Multilingual UI + AI output (EN / 繁體中文 / 简体中文)
• [x] Disk module (hotspots + full deep scan + growth) and cleanup-plan engine
• [x] 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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 0x0funky
• Source: 0x0funky/Agentinel
• License: MIT

Install and usage instructions live in the source repository linked above.