<p align="center">
<img src="ui/banner.png" alt="Agentinel — a local resource sentinel for the multi-agent era" width="860">
</p>
<p align="center">
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS-3f7bf6" alt="platform">
<img src="https://img.shields.io/badge/python-3.9%2B-1fb877" alt="python">
<img src="https://img.shields.io/badge/UI-EN%20%7C%20%E7%B9%81%E9%AB%94%20%7C%20%E7%AE%80%E4%BD%93-e0962f" alt="languages">
<img src="https://img.shields.io/badge/license-MIT-7c8698" alt="license">
</p>
<p align="center">
<b>English</b> · <a href="README.zh-TW.md">繁體中文</a> · <a href="README.zh-CN.md">简体中文</a>
</p>
---
**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.
<p><img src="docs/menu-bar-app.png" alt="Agentinel menu-bar mini panel" width="360" /></p>
## 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
```bash
pip install -r requirements.txt
```
Python 3.9+. Windows needs the WebView2 Runtime (built into Win11); macOS uses the built-in
WKWebView.
## Run
```bash
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.
```bash
./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`](.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