agenttop 0.10.6 → 0.11.0

package/README.md

@@ -6,6 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/node/v/agenttop.svg)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)](https://www.typescriptlang.org/)
+[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-blue.svg)](#platform-support)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/wrxck/agenttop/pulls)
 [![GitHub code size](https://img.shields.io/github/languages/code-size/wrxck/agenttop)](https://github.com/wrxck/agenttop)
 
@@ -20,6 +21,7 @@ Read more about [why agenttop was built](https://blog.matthesketh.pro/blog/agent
 ## Table of contents
 
 - [Install](#install)
+- [Platform support](#platform-support)
 - [Usage](#usage)
 - [Token usage](#token-usage)
 - [Session nicknames](#session-nicknames)
@@ -30,7 +32,10 @@ Read more about [why agenttop was built](https://blog.matthesketh.pro/blog/agent
 - [Themes](#themes)
 - [Streaming modes](#streaming-modes)
 - [Active protection](#active-protection)
+- [Session status](#session-status)
+- [Pinned sessions](#pinned-sessions)
 - [Security rules](#security-rules)
+- [Custom alerts](#custom-alerts)
 - [MCP server](#mcp-server)
 - [Notifications](#notifications)
 - [Alert logging](#alert-logging)
@@ -45,6 +50,8 @@ Read more about [why agenttop was built](https://blog.matthesketh.pro/blog/agent
 
 ## Install
 
+### npm (all platforms)
+
 ```bash
 npx agenttop
 ```
@@ -55,16 +62,74 @@ Or install globally:
 npm install -g agenttop
 ```
 
+### Homebrew (macOS / Linux)
+
+```bash
+brew tap wrxck/tap
+brew install agenttop
+```
+
+### Scoop (Windows)
+
+```powershell
+scoop bucket add wrxck https://github.com/wrxck/scoop-bucket
+scoop install agenttop
+```
+
+### Winget (Windows)
+
+```powershell
+winget install wrxck.agenttop
+```
+
+### AUR (Arch Linux)
+
+```bash
+yay -S agenttop
+```
+
+### Nix
+
+```bash
+nix run github:wrxck/agenttop
+```
+
+### Snap
+
+```bash
+sudo snap install agenttop --classic
+```
+
+## Platform support
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| **Linux** (Ubuntu, Debian, Fedora, Arch, etc.) | Fully supported | Primary development platform |
+| **macOS** (Intel + Apple Silicon) | Fully supported | Uses `lsof` for process CWD resolution |
+| **Windows** (10/11 + Windows Terminal) | Supported | Uses PowerShell for process discovery; `--all-users` not available |
+
+Development and primary testing is done on Ubuntu. If you encounter issues on other platforms, please [open an issue](https://github.com/wrxck/agenttop/issues) or feel free to contribute a fix.
+
+CI runs on all three platforms (Ubuntu, macOS, Windows) across Node.js 18, 20, and 22.
+
+### Platform-specific config paths
+
+| Platform | Config path |
+|----------|-------------|
+| Linux | `~/.config/agenttop/config.json` (respects `XDG_CONFIG_HOME`) |
+| macOS | `~/.config/agenttop/config.json` (respects `XDG_CONFIG_HOME`) |
+| Windows | `%APPDATA%\agenttop\config.json` |
+
 ## Usage
 
 Run `agenttop` in one terminal while running Claude Code sessions in other tabs.
 
 ```
--- agenttop v0.6.0 ---- 3 sessions ---- 14:32:08 ---------------------
+-- agenttop v0.10.7 --- 3 sessions ---- 14:32:08 ---------------------
 | SESSIONS                 | ACTIVITY (cuddly-wiggling-sundae)           |
 |                          |                                             |
-| > cuddly-wiggling-sundae | 14:32:05 Bash    ls /tmp/claude-0/         |
-|   /home/matt | opus      | 14:32:03 Read    /root/.claude/CLAUDE.md   |
+| > cuddly-wiggling-sundae | 14:32:05 Bash    ls -la                    |
+|   /home/matt | opus      | 14:32:03 Read    CLAUDE.md                 |
 |   CPU 20% | 542MB | 3 ag | 14:31:58 Grep    pattern="sessionId"       |
 |   1.2k in | 340 out      | 14:31:55 Write   /home/matt/app/src/...    |
 |                          | 14:31:52 Bash    npm test                  |
@@ -82,7 +147,7 @@ Run `agenttop` in one terminal while running Claude Code sessions in other tabs.
 ```
 agenttop [options]
 
-  --all-users          Monitor all users (root only)
+  --all-users          Monitor all users (root only, Linux/macOS)
   --no-security        Disable security analysis
   --json               Stream events as JSON lines (no TUI)
   --plain              Stream events as plain text (no TUI)
@@ -118,7 +183,7 @@ Press `n` on a selected session to assign a nickname. The nickname replaces the
 
 Press `N` to clear a nickname.
 
-Nicknames are stored in `~/.config/agenttop/config.json`.
+Nicknames are stored in your [config file](#configuration).
 
 ## Session filtering
 
@@ -147,6 +212,30 @@ Press `d` to delete a session. A confirmation prompt appears. On confirm, the se
 
 Sessions with a running process are shown in green. Inactive sessions (no process) are shown in red.
 
+## Session status
+
+agenttop detects four session states:
+
+| Status | Indicator | Meaning |
+|--------|-----------|---------|
+| Waiting | Yellow ● `[waiting]` | Claude has asked a question and is waiting for your input |
+| Stale | Orange ● `[stale]` | Process is running but no output for the configured timeout |
+| Active | Green ● | Actively processing |
+| Inactive | Grey ○ | Process has ended |
+
+Sessions sort by status priority: waiting > stale > active > inactive, then by last activity within each group.
+
+The stale timeout (default 60s) can be adjusted in the Alert Rules menu (`r`).
+
+## Pinned sessions
+
+Press `p` to pin a session to the top of the list. Pinned sessions always appear above non-pinned sessions, regardless of status.
+
+- `p` — toggle pin on selected session
+- `P` — move pinned session up in pin order
+
+Pinned sessions show a `*` marker next to the status dot. Pin order persists across restarts.
+
 ## Session detail view
 
 Press `Enter` on a session to open the detail view, which shows:
@@ -174,9 +263,9 @@ Press `x` again to exit split mode and return to the single-panel layout.
 
 ## Themes
 
-agenttop ships with 15 built-in colour themes and a full theme management system. Open Settings (`s`) and select **Manage themes...** to access the theme menu.
+agenttop ships with 27 built-in colour themes and a full theme management system. Open Settings (`s`) and select **Manage themes...** to access the theme menu.
 
-Built-in themes: One Dark (default), Dracula, Monokai Pro, Solarized Dark, Solarized Light, Nord, Gruvbox Dark, Tokyo Night, Catppuccin Mocha, Catppuccin Latte, Rose Pine, Rose Pine Moon, Pastel Dark, Kanagawa, and Everforest.
+Built-in themes: One Dark (default), Dracula, Monokai Pro, Solarized Dark, Solarized Light, Nord, Gruvbox Dark, Tokyo Night, Catppuccin Mocha, Catppuccin Latte, Rose Pine, Rose Pine Moon, Pastel Dark, Kanagawa, Everforest, Hi Feline, Plumber Bros, Hedgehog Speed, Block Craft, Galaxy Conflicts, Pocket Creatures, Brick Wizard, Caped Knight, Web Crawler, Frozen Kingdom, Coral Reef, and Toy Ranch.
 
 In the theme menu:
 
@@ -188,7 +277,7 @@ In the theme menu:
 - **Delete** — press `d` to delete a custom theme
 - **Restore default** — press `Backspace` to reset to One Dark
 
-Custom themes are saved to `~/.config/agenttop/config.json` and persist across sessions.
+Custom themes are saved to your [config file](#configuration) and persist across sessions.
 
 ## Streaming modes
 
@@ -217,7 +306,7 @@ agenttop --plain > session.log
 Output format:
 ```
 SESSION cuddly-wiggling-sundae | opus | /home/matt | CPU 20% | 542MB | 1.2k in / 340 out
-14:32:05 cuddly-wiggling-sundae Bash     ls /tmp/claude-0/
+14:32:05 cuddly-wiggling-sundae Bash     ls -la
 ALERT 14:32:10 [warn] cuddly-wiggling-sundae: curl to external URL
 USAGE abc123 +100 in / +50 out
 ```
@@ -258,6 +347,38 @@ Individual rules can be disabled in the config file under `security.rules`.
 
 Alerts are deduplicated within a 30-second window.
 
+## Custom alerts
+
+Define custom alert rules with regex patterns to match against tool activity.
+
+Press `r` to open the Alert Rules menu where you can:
+
+- Toggle built-in security rules on/off
+- Add custom rules with regex patterns
+- Choose what to match: tool input, output, tool name, or all
+- Set severity level per rule
+- Adjust the stale session timeout
+
+Custom rules can also be defined in your config file:
+
+```json
+{
+  "alerts": {
+    "staleTimeout": 60,
+    "custom": [
+      {
+        "name": "dangerous-rm",
+        "pattern": "rm\\s+-rf\\s+/",
+        "match": "input",
+        "severity": "high",
+        "message": "Dangerous recursive delete detected",
+        "enabled": true
+      }
+    ]
+  }
+}
+```
+
 ## MCP server
 
 agenttop can run as an MCP server, letting Claude Code query session status, alerts, and usage directly:
@@ -275,6 +396,15 @@ Available tools:
 | `agenttop_alerts` | Get recent security alerts (filterable by severity) |
 | `agenttop_usage` | Get token usage for a session or all sessions |
 | `agenttop_activity` | Get recent tool calls for a session |
+| `agenttop_waiting_sessions` | List sessions in waiting or stale state |
+| `agenttop_session_status` | Get status for a specific session |
+| `agenttop_custom_alerts` | List configured custom alert rules |
+| `agenttop_set_custom_alert` | Add or update a custom alert rule |
+| `agenttop_delete_custom_alert` | Delete a custom alert rule |
+| `agenttop_alert_history` | Get recent alerts with severity filter |
+| `agenttop_set_stale_timeout` | Set the stale timeout |
+| `agenttop_pin_session` | Pin a session to the top |
+| `agenttop_unpin_session` | Unpin a session |
 
 You can also run the MCP server directly via `agenttop-mcp` (installed as a separate bin).
 
@@ -283,15 +413,15 @@ You can also run the MCP server directly via `agenttop-mcp` (installed as a sepa
 When security alerts are raised:
 
 - **Terminal bell** — `\x07` on high/critical alerts (configurable)
-- **Desktop notification** — via `notify-send` (linux) or `osascript` (macOS) for critical alerts
+- **Desktop notification** — via `notify-send` (Linux), `osascript` (macOS), or PowerShell toast (Windows)
 
 Rate-limited to max 1 desktop notification per 30 seconds.
 
-Configure in `config.json` under `notifications`, or disable entirely with `--no-notify`.
+Configure in your [config file](#configuration) under `notifications`, or disable entirely with `--no-notify`.
 
 ## Alert logging
 
-Alerts are logged to `~/.config/agenttop/alerts.jsonl` by default. One JSON line per alert.
+Alerts are logged to `alerts.jsonl` in your [config directory](#platform-specific-config-paths) by default. One JSON line per alert.
 
 The log file rotates when it exceeds 10MB (keeps 2 rotated files).
 
@@ -309,7 +439,7 @@ Disable with `--no-updates` or set `updates.checkOnLaunch: false` in config.
 
 ## Configuration
 
-Config file at `~/.config/agenttop/config.json` (respects `XDG_CONFIG_HOME`):
+Config file location depends on your platform — see [platform-specific config paths](#platform-specific-config-paths).
 
 ```json
 {
@@ -324,7 +454,9 @@ Config file at `~/.config/agenttop/config.json` (respects `XDG_CONFIG_HOME`):
   },
   "alerts": {
     "logFile": "~/.config/agenttop/alerts.jsonl",
-    "enabled": true
+    "enabled": true,
+    "staleTimeout": 60,
+    "custom": []
   },
   "updates": {
     "checkOnLaunch": true,
@@ -351,13 +483,17 @@ Config file at `~/.config/agenttop/config.json` (respects `XDG_CONFIG_HOME`):
     "pinLeft": "1",
     "pinRight": "2",
     "swapPanels": "S",
-    "closePanel": "X"
+    "closePanel": "X",
+    "alertRules": "r",
+    "pin": "p",
+    "pinUp": "P"
   },
   "theme": "one-dark",
   "customThemes": {},
   "nicknames": {},
   "archived": {},
   "archiveExpiryDays": 0,
+  "pinnedSessions": [],
   "security": {
     "enabled": true,
     "rules": {
@@ -400,18 +536,21 @@ Default keybindings:
 | `1` / `2` | Pin session to left / right panel (split mode) |
 | `S` | Swap left and right panels (split mode) |
 | `X` | Close focused panel (split mode) |
+| `r` | Open alert rules menu |
+| `p` | Toggle pin on selected session |
+| `P` | Move pinned session up |
 | `q` | Quit |
 
 ## How it works
 
-agenttop reads Claude Code's task output files from `/tmp/claude-<uid>/` using inotify-based file watching via [chokidar](https://github.com/paulmillr/chokidar). Each session writes JSONL events containing tool calls, tool results, and token usage, which agenttop parses and displays in real-time.
+agenttop reads Claude Code's session output files using cross-platform file watching via [chokidar](https://github.com/paulmillr/chokidar) (inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows). Each session writes JSONL events containing tool calls, tool results, and token usage, which agenttop parses and displays in real-time.
 
-Three runtime dependencies: [ink](https://github.com/vadimdemedes/ink) (React-based TUI), chokidar (file watching), and [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) (MCP server). Everything else is Node built-ins.
+Four runtime dependencies: [ink](https://github.com/vadimdemedes/ink) and [react](https://react.dev/) (React-based TUI), [chokidar](https://github.com/paulmillr/chokidar) (file watching), and [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) (MCP server). Everything else is Node built-ins.
 
 ## Multi-user support
 
 - **Non-root** — monitors your own sessions only
-- **Root** — use `--all-users` to monitor all users' sessions on the machine
+- **Root** — use `--all-users` to monitor all users' sessions on the machine (Linux/macOS only)
 
 ## Contributing
 
@@ -421,8 +560,7 @@ Ideas for contributions:
 
 - Support for additional agent platforms beyond Claude Code
 - New security rules
-- Themes and colour customisation
-- Windows support
+- Platform-specific improvements
 
 ## Trademark notice