agent-usage-manager 0.1.0__tar.gz

agent_usage_manager-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+.DS_Store
+agents.local.yaml
+dist/
+build/
+*.egg-info/

agent_usage_manager-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_usage_manager-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: agent-usage-manager
+Version: 0.1.0
+Summary: htop for AI agents — liveness, CPU/mem/GPU usage, and a kill switch for headless agents (openclaw, hermes, ollama, vllm, claude-code).
+Project-URL: Homepage, https://github.com/minglong51/agent-usage-manager
+Project-URL: Repository, https://github.com/minglong51/agent-usage-manager
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,gpu,llm,monitoring,observability,ollama,vllm
+Requires-Python: >=3.9
+Requires-Dist: fastapi>=0.110
+Requires-Dist: psutil>=5.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uvicorn[standard]>=0.27
+Description-Content-Type: text/markdown
+
+# agent-usage-manager
+
+A tiny, single-file web dashboard for **headless AI agents** running on a machine —
+OpenClaw, Hermes, Claude Code, Ollama, vLLM, llama.cpp, or anything you name. It
+shows which agents are alive and what they're costing you (CPU, memory, GPU), and
+gives you a **kill button** per agent.
+
+No database, no auth layer, no dependencies beyond FastAPI + psutil. Runs on
+macOS and Linux. Meant to be cloned, configured, and run on any node in a fleet.
+
+```
+AGENT          PID    STATUS     CPU %   MEM MB   GPU MB   UPTIME   COMMAND          ┆
+openclaw +3    48213  ● running    62.4    1840     7320     2h 11m  openclaw serve … [kill] [force]
+claude-code +9 73590  ● running    97.4    7630        —     1h 02m  claude --chann … [kill] [force]
+hermes         49001  ● running    18.0     512        —     44m     hermes worker …  [kill] [force]
+ollama         50122  ● running     3.1    9210    14080     6h 02m  ollama runner …  [kill] [force]
+```
+(`+N` = child processes rolled up under the agent; CPU/mem/GPU are tree totals.)
+
+> A live web UI (auto-refreshing every 3s). The rendered GIF lands here once recorded —
+> see `demo.tape`.
+
+## What it does
+
+- **One row per agent.** Agents are grouped by process tree — the spawned children
+  of an agent (inference subprocesses, MCP servers, helpers) are rolled up under it
+  with a `+N` badge instead of cluttering the list as separate rows.
+- **Liveness** — green dot = running, red = zombie/dead. Status column shows the OS state.
+- **Usage** — CPU %, resident memory (MB), GPU memory (MB, NVIDIA only), and uptime,
+  refreshed every 3s. **CPU/mem/GPU are tree totals** — the agent's true cost including
+  everything it spawned.
+- **Kill the tree** — `kill` sends SIGTERM to the agent *and its children* (so spawned
+  helpers don't leak resources), `force` sends SIGKILL. SIGTERM auto-escalates to
+  SIGKILL after 3s. The confirm dialog tells you how many child processes will stop.
+
+## Safety
+
+This is the important part — a web page that can kill processes needs guardrails:
+
+- **Allowlist only.** Only processes matching a pattern in `agents.yaml` are ever
+  listed *or* killable. The kill endpoint re-checks the match server-side before
+  sending any signal, so the dashboard can never be used to kill an arbitrary PID.
+- **Protected patterns.** Anything matching `protect:` in `agents.yaml` — plus the
+  monitor's own process and PID 1 — shows a disabled, greyed-out kill button and is
+  refused server-side.
+- **Secret redaction.** Command lines often carry tokens/keys in env vars or flags
+  (`FOO_TOKEN=...`, `--api-key ...`, `sk-...`, `ghp_...`, JWTs). The command column
+  redacts these to `***` before they ever reach the browser — safe to screenshot.
+- **Bind local by default.** It listens on `127.0.0.1`. Don't expose it to a network
+  without putting auth in front of it (reverse proxy + basic auth, SSH tunnel, etc.) —
+  it has no built-in authentication.
+
+## Quick start
+
+Run it without installing anything (needs [`uv`](https://github.com/astral-sh/uv)):
+
+```bash
+uvx agent-usage-manager
+# open http://127.0.0.1:8765
+```
+
+Or install it:
+
+```bash
+pipx install agent-usage-manager   # or: pip install agent-usage-manager
+agent-usage-manager --port 8765
+```
+
+From a clone (for hacking on it):
+
+```bash
+git clone <this-repo> && cd agent-usage-manager
+./run.sh                           # venv + editable install, serves on :8765
+```
+
+Flags: `--host`, `--port`, `--config /path/to/agents.yaml`.
+
+## Configure which processes are "agents"
+
+Edit `agents.yaml`:
+
+```yaml
+agents:
+  - label: openclaw           # shown as the badge in the UI
+    match: openclaw           # case-insensitive substring of the command line
+  - label: hermes
+    match: hermes
+  - label: claude-code
+    match: "claude(\\s|$|-code)"
+    regex: true               # treat `match` as a regex instead of substring
+
+protect:                      # never killable, even if matched above
+  - uvicorn
+```
+
+A process matches if the pattern hits its **full command line** or its process name.
+Point at a different file with `AGENTS_CONFIG=/path/to/agents.yaml`.
+
+## GPU notes
+
+Per-process GPU memory comes from `nvidia-smi` when it's on `PATH` (Linux / NVIDIA).
+**Apple Silicon has no per-process GPU accounting API**, so the GPU column stays blank
+on Macs — CPU and memory are the meaningful resource signals there.
+
+## API
+
+- `GET  /api/agents` → `{ agents: [...], host, cpu_count, ts }`
+- `POST /api/kill/{pid}?force=false` → SIGTERM (or SIGKILL with `force=true`)
+
+## Run as a service
+
+Linux (systemd), `~/.config/systemd/user/agent-usage-manager.service`:
+
+```ini
+[Unit]
+Description=agent usage manager
+[Service]
+ExecStart=%h/agent-usage-manager/.venv/bin/uvicorn app:app --port 8765
+WorkingDirectory=%h/agent-usage-manager
+Restart=on-failure
+[Install]
+WantedBy=default.target
+```
+
+```bash
+systemctl --user enable --now agent-usage-manager
+```
+
+## License
+
+MIT

agent_usage_manager-0.1.0/README.md

@@ -0,0 +1,131 @@
+# agent-usage-manager
+
+A tiny, single-file web dashboard for **headless AI agents** running on a machine —
+OpenClaw, Hermes, Claude Code, Ollama, vLLM, llama.cpp, or anything you name. It
+shows which agents are alive and what they're costing you (CPU, memory, GPU), and
+gives you a **kill button** per agent.
+
+No database, no auth layer, no dependencies beyond FastAPI + psutil. Runs on
+macOS and Linux. Meant to be cloned, configured, and run on any node in a fleet.
+
+```
+AGENT          PID    STATUS     CPU %   MEM MB   GPU MB   UPTIME   COMMAND          ┆
+openclaw +3    48213  ● running    62.4    1840     7320     2h 11m  openclaw serve … [kill] [force]
+claude-code +9 73590  ● running    97.4    7630        —     1h 02m  claude --chann … [kill] [force]
+hermes         49001  ● running    18.0     512        —     44m     hermes worker …  [kill] [force]
+ollama         50122  ● running     3.1    9210    14080     6h 02m  ollama runner …  [kill] [force]
+```
+(`+N` = child processes rolled up under the agent; CPU/mem/GPU are tree totals.)
+
+> A live web UI (auto-refreshing every 3s). The rendered GIF lands here once recorded —
+> see `demo.tape`.
+
+## What it does
+
+- **One row per agent.** Agents are grouped by process tree — the spawned children
+  of an agent (inference subprocesses, MCP servers, helpers) are rolled up under it
+  with a `+N` badge instead of cluttering the list as separate rows.
+- **Liveness** — green dot = running, red = zombie/dead. Status column shows the OS state.
+- **Usage** — CPU %, resident memory (MB), GPU memory (MB, NVIDIA only), and uptime,
+  refreshed every 3s. **CPU/mem/GPU are tree totals** — the agent's true cost including
+  everything it spawned.
+- **Kill the tree** — `kill` sends SIGTERM to the agent *and its children* (so spawned
+  helpers don't leak resources), `force` sends SIGKILL. SIGTERM auto-escalates to
+  SIGKILL after 3s. The confirm dialog tells you how many child processes will stop.
+
+## Safety
+
+This is the important part — a web page that can kill processes needs guardrails:
+
+- **Allowlist only.** Only processes matching a pattern in `agents.yaml` are ever
+  listed *or* killable. The kill endpoint re-checks the match server-side before
+  sending any signal, so the dashboard can never be used to kill an arbitrary PID.
+- **Protected patterns.** Anything matching `protect:` in `agents.yaml` — plus the
+  monitor's own process and PID 1 — shows a disabled, greyed-out kill button and is
+  refused server-side.
+- **Secret redaction.** Command lines often carry tokens/keys in env vars or flags
+  (`FOO_TOKEN=...`, `--api-key ...`, `sk-...`, `ghp_...`, JWTs). The command column
+  redacts these to `***` before they ever reach the browser — safe to screenshot.
+- **Bind local by default.** It listens on `127.0.0.1`. Don't expose it to a network
+  without putting auth in front of it (reverse proxy + basic auth, SSH tunnel, etc.) —
+  it has no built-in authentication.
+
+## Quick start
+
+Run it without installing anything (needs [`uv`](https://github.com/astral-sh/uv)):
+
+```bash
+uvx agent-usage-manager
+# open http://127.0.0.1:8765
+```
+
+Or install it:
+
+```bash
+pipx install agent-usage-manager   # or: pip install agent-usage-manager
+agent-usage-manager --port 8765
+```
+
+From a clone (for hacking on it):
+
+```bash
+git clone <this-repo> && cd agent-usage-manager
+./run.sh                           # venv + editable install, serves on :8765
+```
+
+Flags: `--host`, `--port`, `--config /path/to/agents.yaml`.
+
+## Configure which processes are "agents"
+
+Edit `agents.yaml`:
+
+```yaml
+agents:
+  - label: openclaw           # shown as the badge in the UI
+    match: openclaw           # case-insensitive substring of the command line
+  - label: hermes
+    match: hermes
+  - label: claude-code
+    match: "claude(\\s|$|-code)"
+    regex: true               # treat `match` as a regex instead of substring
+
+protect:                      # never killable, even if matched above
+  - uvicorn
+```
+
+A process matches if the pattern hits its **full command line** or its process name.
+Point at a different file with `AGENTS_CONFIG=/path/to/agents.yaml`.
+
+## GPU notes
+
+Per-process GPU memory comes from `nvidia-smi` when it's on `PATH` (Linux / NVIDIA).
+**Apple Silicon has no per-process GPU accounting API**, so the GPU column stays blank
+on Macs — CPU and memory are the meaningful resource signals there.
+
+## API
+
+- `GET  /api/agents` → `{ agents: [...], host, cpu_count, ts }`
+- `POST /api/kill/{pid}?force=false` → SIGTERM (or SIGKILL with `force=true`)
+
+## Run as a service
+
+Linux (systemd), `~/.config/systemd/user/agent-usage-manager.service`:
+
+```ini
+[Unit]
+Description=agent usage manager
+[Service]
+ExecStart=%h/agent-usage-manager/.venv/bin/uvicorn app:app --port 8765
+WorkingDirectory=%h/agent-usage-manager
+Restart=on-failure
+[Install]
+WantedBy=default.target
+```
+
+```bash
+systemctl --user enable --now agent-usage-manager
+```
+
+## License
+
+MIT

agent_usage_manager-0.1.0/agent_usage_manager/agents.yaml

@@ -0,0 +1,34 @@
+# Which processes count as "agents". A process matches if the pattern hits its
+# executable name + first few arguments (case-insensitive substring or regex) —
+# NOT the entire command line, so a process that merely mentions an agent name
+# deep in its args (e.g. inside a system prompt) is not misclassified.
+# Only processes that match here can be listed AND killed — the kill endpoint
+# re-checks the match before sending a signal, so the dashboard can never be
+# used to kill an arbitrary unrelated PID.
+#
+# Matched processes are grouped by process tree: one row per agent (the root),
+# with child processes rolled up. CPU/mem/GPU are tree totals, and "kill" stops
+# the whole tree (root + children) so spawned helpers don't leak resources.
+agents:
+  - label: openclaw
+    match: openclaw
+  - label: hermes
+    match: hermes
+  - label: claude-code
+    match: "claude(\\s|$|-code)"
+    regex: true
+  - label: ollama
+    match: ollama
+  - label: vllm
+    match: vllm
+  - label: llama.cpp
+    match: llama-server
+
+# Patterns that must NEVER be killed even if they match an agent pattern above.
+# Self (this monitor's own PID) and PID 1 are always protected in code.
+protect:
+  - agent-usage-manager
+  - uvicorn
+
+# GPU sampling: nvidia-smi is used automatically when present (Linux/NVIDIA).
+# On Apple Silicon there is no per-process GPU API, so the GPU column is blank.

agent_usage_manager-0.1.0/agent_usage_manager/app.py

@@ -0,0 +1,375 @@
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import signal
+import subprocess
+import time
+from pathlib import Path
+from typing import Optional
+
+import psutil
+import yaml
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+BASE = Path(__file__).parent
+
+
+def _resolve_config() -> Path:
+    env = os.environ.get("AGENTS_CONFIG")
+    if env:
+        return Path(env)
+    cwd_cfg = Path.cwd() / "agents.yaml"
+    if cwd_cfg.exists():
+        return cwd_cfg
+    return BASE / "agents.yaml"
+
+
+CONFIG_PATH = _resolve_config()
+
+
+class Matcher:
+    def __init__(self, label: str, pattern: str, is_regex: bool) -> None:
+        self.label = label
+        self.is_regex = is_regex
+        self.raw = pattern
+        self.rx = re.compile(pattern, re.IGNORECASE) if is_regex else None
+        self.lower = pattern.lower()
+
+    def matches(self, text: str) -> bool:
+        if self.rx is not None:
+            return self.rx.search(text) is not None
+        return self.lower in text.lower()
+
+
+def load_config() -> tuple[list[Matcher], list[str]]:
+    data = yaml.safe_load(CONFIG_PATH.read_text())
+    matchers = [
+        Matcher(a["label"], a["match"], bool(a.get("regex", False)))
+        for a in data.get("agents", [])
+    ]
+    protect = [p.lower() for p in data.get("protect", [])]
+    return matchers, protect
+
+
+MATCHERS, PROTECT = load_config()
+SELF_PID = os.getpid()
+
+
+_SECRET_KV = re.compile(
+    r"(?i)([\w.-]*(?:token|key|secret|password|passwd|api[_-]?key|auth)[\w.-]*\s*[=:]\s*)\S+"
+)
+_SECRET_FLAG = re.compile(
+    r"(?i)(--?(?:token|key|secret|password|api[_-]?key|auth)\S*\s+)\S+"
+)
+_SECRET_VALUE = re.compile(
+    r"\b(sk-[A-Za-z0-9]{8,}|gh[pousr]_[A-Za-z0-9]{8,}|xox[bap]-[A-Za-z0-9-]{8,}|eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,})"
+)
+
+
+def _redact(text: str) -> str:
+    text = _SECRET_KV.sub(r"\1***", text)
+    text = _SECRET_FLAG.sub(r"\1***", text)
+    text = _SECRET_VALUE.sub("***", text)
+    return text
+
+
+def _cmdline(proc: psutil.Process) -> str:
+    try:
+        raw = " ".join(proc.cmdline()) or proc.name()
+    except (psutil.AccessDenied, psutil.ZombieProcess, psutil.NoSuchProcess):
+        try:
+            raw = proc.name()
+        except psutil.Error:
+            return ""
+    return _redact(raw)
+
+
+def _match_target(proc: psutil.Process) -> str:
+    """Text used for agent matching: the executable basename + first few args.
+
+    Deliberately NOT the full command line — a long embedded argument (e.g. a
+    system prompt that happens to contain the word "claude") must not cause a
+    parent/wrapper process to be misclassified as an agent.
+    """
+    try:
+        argv = proc.cmdline()
+    except (psutil.AccessDenied, psutil.ZombieProcess, psutil.NoSuchProcess):
+        argv = []
+    if argv:
+        head = argv[:4]
+        if head[0]:
+            head[0] = os.path.basename(head[0])
+        return " ".join(head)
+    try:
+        return proc.name()
+    except psutil.Error:
+        return ""
+
+
+def _label_for(text: str) -> Optional[str]:
+    for m in MATCHERS:
+        if m.matches(text):
+            return m.label
+    return None
+
+
+def _is_protected(text: str, pid: int) -> bool:
+    if pid in (SELF_PID, 1):
+        return True
+    low = text.lower()
+    return any(p in low for p in PROTECT)
+
+
+def _gpu_by_pid() -> dict[int, float]:
+    """Best-effort per-process GPU memory (MiB) via nvidia-smi. Empty on macOS."""
+    if not shutil.which("nvidia-smi"):
+        return {}
+    try:
+        out = subprocess.run(
+            [
+                "nvidia-smi",
+                "--query-compute-apps=pid,used_memory",
+                "--format=csv,noheader,nounits",
+            ],
+            capture_output=True,
+            text=True,
+            timeout=4,
+        ).stdout
+    except (subprocess.SubprocessError, OSError):
+        return {}
+    result: dict[int, float] = {}
+    for line in out.strip().splitlines():
+        parts = [p.strip() for p in line.split(",")]
+        if len(parts) == 2 and parts[0].isdigit():
+            result[int(parts[0])] = float(parts[1])
+    return result
+
+
+app = FastAPI(title="agent-usage-manager")
+
+# Persistent Process handles so cpu_percent() reports usage since the last poll.
+_handles: dict[int, psutil.Process] = {}
+
+
+class Agent(BaseModel):
+    pid: int
+    label: str
+    name: str
+    cmdline: str
+    status: str
+    alive: bool
+    cpu_percent: float
+    mem_mb: float
+    gpu_mem_mb: Optional[float]
+    uptime_s: float
+    child_count: int
+    protected: bool
+
+
+def _collect() -> tuple[dict, dict, dict, dict]:
+    """One pass over all processes.
+
+    Returns (meta, children, label_of, procmap):
+      meta[pid]     = {ppid, name, status, ct}
+      children[ppid]= [pid, ...]
+      label_of[pid] = matcher label (only present for matched processes)
+      procmap[pid]  = the psutil.Process from this poll
+    """
+    meta: dict[int, dict] = {}
+    children: dict[int, list[int]] = {}
+    label_of: dict[int, str] = {}
+    procmap: dict[int, psutil.Process] = {}
+    for proc in psutil.process_iter(["pid", "ppid", "name", "status", "create_time"]):
+        pid = proc.info["pid"]
+        ppid = proc.info.get("ppid") or 0
+        name = proc.info.get("name") or ""
+        meta[pid] = {
+            "ppid": ppid,
+            "name": name,
+            "status": proc.info.get("status") or "?",
+            "ct": proc.info.get("create_time"),
+        }
+        children.setdefault(ppid, []).append(pid)
+        procmap[pid] = proc
+        label = _label_for(_match_target(proc)) or _label_for(name)
+        if label:
+            label_of[pid] = label
+    return meta, children, label_of, procmap
+
+
+def _ancestors(pid: int, meta: dict):
+    seen: set[int] = set()
+    cur = meta.get(pid, {}).get("ppid", 0)
+    while cur and cur not in seen:
+        seen.add(cur)
+        yield cur
+        cur = meta.get(cur, {}).get("ppid", 0)
+
+
+def _descendants(root: int, children: dict) -> list[int]:
+    out: list[int] = []
+    stack = list(children.get(root, []))
+    seen: set[int] = set()
+    while stack:
+        p = stack.pop()
+        if p in seen:
+            continue
+        seen.add(p)
+        out.append(p)
+        stack.extend(children.get(p, []))
+    return out
+
+
+def _cpu_mem(pid: int, procmap: dict) -> tuple[float, float]:
+    handle = _handles.get(pid)
+    if handle is None or handle.pid != pid:
+        handle = procmap.get(pid)
+        if handle is None:
+            try:
+                handle = psutil.Process(pid)
+            except psutil.NoSuchProcess:
+                return 0.0, 0.0
+        _handles[pid] = handle
+        try:
+            handle.cpu_percent(None)
+        except psutil.Error:
+            pass
+    try:
+        return handle.cpu_percent(None), handle.memory_info().rss / (1024 * 1024)
+    except psutil.Error:
+        return 0.0, 0.0
+
+
+@app.get("/api/agents")
+def list_agents() -> dict:
+    gpu = _gpu_by_pid()
+    now = time.time()
+    meta, children, label_of, procmap = _collect()
+    matched = set(label_of)
+
+    # An agent's "root" is a matched process with no matched ancestor; any matched
+    # descendant is rolled up into it rather than shown as its own row.
+    roots = [
+        pid
+        for pid in matched
+        if not any(a in matched for a in _ancestors(pid, meta))
+    ]
+
+    agents: list[Agent] = []
+    for root in roots:
+        subtree = [root] + _descendants(root, children)
+        cpu = mem = gpu_sum = 0.0
+        has_gpu = False
+        for p in subtree:
+            c, m = _cpu_mem(p, procmap)
+            cpu += c
+            mem += m
+            if p in gpu:
+                gpu_sum += gpu[p]
+                has_gpu = True
+        info = meta[root]
+        rproc = procmap.get(root)
+        cmd = _cmdline(rproc) if rproc else info["name"]
+        ct = info["ct"] or now
+        agents.append(
+            Agent(
+                pid=root,
+                label=label_of[root],
+                name=info["name"],
+                cmdline=cmd[:300],
+                status=info["status"],
+                alive=info["status"] != psutil.STATUS_ZOMBIE,
+                cpu_percent=round(cpu, 1),
+                mem_mb=round(mem, 1),
+                gpu_mem_mb=round(gpu_sum, 1) if has_gpu else None,
+                uptime_s=round(now - ct, 0),
+                child_count=len(subtree) - 1,
+                protected=_is_protected(
+                    _match_target(rproc) if rproc else info["name"], root
+                ),
+            )
+        )
+
+    live = set(meta)
+    for pid in list(_handles):
+        if pid not in live:
+            _handles.pop(pid, None)
+
+    agents.sort(key=lambda a: a.cpu_percent, reverse=True)
+    return {
+        "agents": [a.model_dump() for a in agents],
+        "host": psutil.os.uname().nodename if hasattr(psutil.os, "uname") else "",
+        "cpu_count": psutil.cpu_count(),
+        "ts": now,
+    }
+
+
+def _signal_tree(root_pid: int, sig: signal.Signals) -> list[psutil.Process]:
+    """Send `sig` to the root and every descendant, skipping self/PID 1/protected."""
+    _, children, _, procmap = _collect()
+    victims = [root_pid] + _descendants(root_pid, children)
+    signaled: list[psutil.Process] = []
+    for p in victims:
+        if p in (SELF_PID, 1):
+            continue
+        proc = procmap.get(p)
+        if proc is None:
+            try:
+                proc = psutil.Process(p)
+            except psutil.NoSuchProcess:
+                continue
+        try:
+            if _is_protected(_match_target(proc), p):
+                continue
+            proc.send_signal(sig)
+            signaled.append(proc)
+        except psutil.Error:
+            pass
+    return signaled
+
+
+@app.post("/api/kill/{pid}")
+def kill_agent(pid: int, force: bool = False) -> dict:
+    try:
+        proc = psutil.Process(pid)
+    except psutil.NoSuchProcess:
+        raise HTTPException(404, f"PID {pid} not found")
+
+    target = _match_target(proc)
+    if _label_for(target) is None and _label_for(proc.name()) is None:
+        raise HTTPException(403, f"PID {pid} is not a recognized agent — refusing")
+    if _is_protected(target, pid):
+        raise HTTPException(403, f"PID {pid} is protected — refusing")
+
+    sig = signal.SIGKILL if force else signal.SIGTERM
+    signaled = _signal_tree(pid, sig)
+    gone, alive = psutil.wait_procs(signaled, timeout=3)
+    if alive and not force:
+        for p in alive:
+            try:
+                p.send_signal(signal.SIGKILL)
+            except psutil.Error:
+                pass
+        more_gone, alive = psutil.wait_procs(alive, timeout=3)
+        gone += more_gone
+
+    return {
+        "pid": pid,
+        "result": "terminated" if not alive else "signal sent, some still running",
+        "signal": sig.name,
+        "killed": len(gone),
+        "still_running": len(alive),
+    }
+
+
+@app.get("/")
+def index() -> FileResponse:
+    return FileResponse(BASE / "static" / "index.html")
+
+
+app.mount("/static", StaticFiles(directory=BASE / "static"), name="static")

agent_usage_manager-0.1.0/agent_usage_manager/cli.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import argparse
+import os
+
+import uvicorn
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="agent-usage-manager",
+        description="Web dashboard for headless AI agents: liveness, CPU/mem/GPU, kill.",
+    )
+    parser.add_argument("--host", default=os.environ.get("HOST", "127.0.0.1"))
+    parser.add_argument("--port", type=int, default=int(os.environ.get("PORT", "8765")))
+    parser.add_argument(
+        "--config",
+        default=None,
+        help="Path to agents.yaml (default: ./agents.yaml, else bundled).",
+    )
+    args = parser.parse_args()
+    if args.config:
+        os.environ["AGENTS_CONFIG"] = args.config
+
+    print(f"agent-usage-manager → http://{args.host}:{args.port}")
+    uvicorn.run("agent_usage_manager.app:app", host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

agent_usage_manager-0.1.0/agent_usage_manager/static/index.html

@@ -0,0 +1,129 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>agent usage manager</title>
+<style>
+  :root { color-scheme: dark; }
+  body { font: 14px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace;
+         margin: 0; background: #0d1117; color: #c9d1d9; }
+  header { padding: 14px 20px; border-bottom: 1px solid #21262d;
+           display: flex; align-items: baseline; gap: 16px; flex-wrap: wrap; }
+  h1 { font-size: 16px; margin: 0; }
+  .meta { color: #8b949e; font-size: 12px; }
+  .dot { display: inline-block; width: 8px; height: 8px; border-radius: 50%;
+         margin-right: 6px; vertical-align: middle; }
+  .live { background: #3fb950; } .dead { background: #f85149; }
+  table { width: 100%; border-collapse: collapse; }
+  th, td { text-align: left; padding: 8px 12px; border-bottom: 1px solid #161b22;
+           white-space: nowrap; }
+  th { color: #8b949e; font-weight: 600; font-size: 12px; text-transform: uppercase;
+       letter-spacing: .04em; }
+  td.cmd { white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+           max-width: 380px; color: #8b949e; }
+  td.num { text-align: right; font-variant-numeric: tabular-nums; }
+  .label { background: #1f6feb33; color: #79c0ff; padding: 1px 7px;
+           border-radius: 10px; font-size: 12px; }
+  .kids { color: #8b949e; font-size: 11px; margin-left: 5px; cursor: help; }
+  .bar { height: 5px; background: #21262d; border-radius: 3px; margin-top: 3px; }
+  .bar > i { display: block; height: 100%; border-radius: 3px; background: #d29922; }
+  button.kill { background: #da3633; color: #fff; border: 0; padding: 5px 12px;
+                border-radius: 6px; cursor: pointer; font: inherit; }
+  button.kill:hover { background: #f85149; }
+  button.kill:disabled { background: #30363d; color: #6e7681; cursor: not-allowed; }
+  .empty { padding: 40px 20px; color: #8b949e; }
+  .err { color: #f85149; }
+</style>
+</head>
+<body>
+<header>
+  <h1>agent usage manager</h1>
+  <span class="meta" id="meta">loading…</span>
+  <span class="meta" id="err"></span>
+</header>
+<table>
+  <thead>
+    <tr>
+      <th>agent</th><th>pid</th><th>status</th>
+      <th class="num">cpu %</th><th class="num">mem MB</th>
+      <th class="num">gpu MB</th><th class="num">uptime</th>
+      <th>command</th><th></th>
+    </tr>
+  </thead>
+  <tbody id="rows"></tbody>
+</table>
+<div class="empty" id="empty" hidden>No matching agents running.</div>
+
+<script>
+const rows = document.getElementById("rows");
+const meta = document.getElementById("meta");
+const errEl = document.getElementById("err");
+const empty = document.getElementById("empty");
+
+function dur(s) {
+  s = Math.max(0, s|0);
+  const d = Math.floor(s/86400), h = Math.floor(s%86400/3600),
+        m = Math.floor(s%3600/60);
+  if (d) return d+"d "+h+"h";
+  if (h) return h+"h "+m+"m";
+  if (m) return m+"m";
+  return s+"s";
+}
+
+async function kill(pid, force, children) {
+  const verb = force ? "FORCE KILL (SIGKILL)" : "kill (SIGTERM)";
+  const kids = children > 0
+    ? ` and its ${children} child process${children > 1 ? "es" : ""}`
+    : "";
+  if (!confirm(verb + " PID " + pid + kids + "?")) return;
+  try {
+    const r = await fetch(`/api/kill/${pid}?force=${force}`, {method: "POST"});
+    const j = await r.json();
+    if (!r.ok) throw new Error(j.detail || r.status);
+    await refresh();
+  } catch (e) { errEl.textContent = "kill failed: " + e.message; }
+}
+
+async function refresh() {
+  let data;
+  try {
+    const r = await fetch("/api/agents");
+    data = await r.json();
+    errEl.textContent = "";
+  } catch (e) { errEl.textContent = "fetch failed: " + e.message; return; }
+
+  const a = data.agents;
+  meta.textContent = `${data.host || "host"} · ${data.cpu_count} cpus · ${a.length} agents · ${new Date(data.ts*1000).toLocaleTimeString()}`;
+  empty.hidden = a.length > 0;
+  rows.innerHTML = a.map(x => {
+    const cpuPct = Math.min(100, x.cpu_percent);
+    const protectedNote = x.protected ? ' title="protected — cannot be killed"' : "";
+    const kids = x.child_count > 0
+      ? ` <span class="kids" title="${x.child_count} child process(es) — CPU/mem/GPU shown are tree totals; kill stops the whole tree">+${x.child_count}</span>`
+      : "";
+    return `<tr>
+      <td><span class="label">${x.label}</span>${kids}</td>
+      <td>${x.pid}</td>
+      <td><span class="dot ${x.alive?'live':'dead'}"></span>${x.status}</td>
+      <td class="num">${x.cpu_percent.toFixed(1)}
+        <div class="bar"><i style="width:${cpuPct}%"></i></div></td>
+      <td class="num">${x.mem_mb.toFixed(0)}</td>
+      <td class="num">${x.gpu_mem_mb==null?'—':x.gpu_mem_mb.toFixed(0)}</td>
+      <td class="num">${dur(x.uptime_s)}</td>
+      <td class="cmd" title="${x.cmdline.replace(/"/g,'&quot;')}">${x.cmdline}</td>
+      <td>
+        <button class="kill" ${x.protected?'disabled':''}${protectedNote}
+          onclick="kill(${x.pid}, false, ${x.child_count})">kill</button>
+        <button class="kill" ${x.protected?'disabled':''}
+          onclick="kill(${x.pid}, true, ${x.child_count})">force</button>
+      </td>
+    </tr>`;
+  }).join("");
+}
+
+refresh();
+setInterval(refresh, 3000);
+</script>
+</body>
+</html>

agent_usage_manager-0.1.0/demo.tape

@@ -0,0 +1,21 @@
+# Generate the README GIF with charm's `vhs`:  vhs demo.tape  ->  demo.gif
+# Install vhs:  brew install vhs   (or see https://github.com/charmbracelet/vhs)
+#
+# This records a terminal launching the tool, then you screen-capture the
+# browser separately — OR point vhs at a headless browser. Simplest path:
+# run the tool, open the page, and use a screen recorder for the web UI.
+# This tape covers the terminal half (the "one line to run it" moment).
+
+Output demo.gif
+Set FontSize 18
+Set Width 1100
+Set Height 420
+Set Theme "Dracula"
+Set Padding 18
+
+Type "uvx agent-usage-manager"
+Sleep 600ms
+Enter
+Sleep 2.5s
+Type "# open http://127.0.0.1:8765  →  see every agent's CPU/RAM/GPU, click kill"
+Sleep 3s

agent_usage_manager-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-usage-manager"
+version = "0.1.0"
+description = "htop for AI agents — liveness, CPU/mem/GPU usage, and a kill switch for headless agents (openclaw, hermes, ollama, vllm, claude-code)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["ai-agents", "monitoring", "gpu", "ollama", "vllm", "llm", "observability"]
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "psutil>=5.9",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/minglong51/agent-usage-manager"
+Repository = "https://github.com/minglong51/agent-usage-manager"
+
+[project.scripts]
+agent-usage-manager = "agent_usage_manager.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["agent_usage_manager"]

agent_usage_manager-0.1.0/requirements.txt

@@ -0,0 +1,4 @@
+fastapi>=0.110
+uvicorn[standard]>=0.27
+psutil>=5.9
+pyyaml>=6.0

agent_usage_manager-0.1.0/run.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")"
+
+if [ ! -d .venv ]; then
+  python3 -m venv .venv
+  ./.venv/bin/pip install -q --upgrade pip
+  ./.venv/bin/pip install -q -e .
+fi
+
+HOST="${HOST:-127.0.0.1}" PORT="${PORT:-8765}" ./.venv/bin/agent-usage-manager "$@"