agenttop 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +136 -0
  3. package/dist/index.js +1241 -0
  4. package/dist/index.js.map +1 -0
  5. package/hooks/agenttop-guard.py +120 -0
  6. package/package.json +44 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Matt Hesketh
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,136 @@
1
+ # agenttop
2
+
3
+ Real-time terminal dashboard for monitoring AI coding agent sessions — like `htop` for agents.
4
+
5
+ Currently supports [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Reads local session data only — no network requests, no API keys.
6
+
7
+ ## Table of contents
8
+
9
+ - [Install](#install)
10
+ - [Usage](#usage)
11
+ - [Active protection](#active-protection)
12
+ - [Security rules](#security-rules)
13
+ - [How it works](#how-it-works)
14
+ - [Multi-user support](#multi-user-support)
15
+ - [Trademark notice](#trademark-notice)
16
+ - [License](#license)
17
+
18
+ ## Install
19
+
20
+ ```bash
21
+ npx agenttop
22
+ ```
23
+
24
+ Or install globally:
25
+
26
+ ```bash
27
+ npm install -g agenttop
28
+ ```
29
+
30
+ ## Usage
31
+
32
+ Run `agenttop` in one terminal while running Claude Code sessions in other tabs.
33
+
34
+ ```
35
+ -- agenttop v1.0.0 ---- 3 sessions ---- 14:32:08 ---------------------
36
+ | SESSIONS | ACTIVITY (cuddly-wiggling-sundae) |
37
+ | | |
38
+ | > cuddly-wiggling-sundae | 14:32:05 Bash ls /tmp/claude-0/ |
39
+ | /home/matt | opus | 14:32:03 Read /root/.claude/CLAUDE.md |
40
+ | CPU 20% | 542MB | 3 ag | 14:31:58 Grep pattern="sessionId" |
41
+ | | 14:31:55 Write /home/matt/app/src/... |
42
+ | jolly-dancing-pickle | 14:31:52 Bash npm test |
43
+ | /home/matt/fleet | son | * ALERT: curl to external URL |
44
+ | | |
45
+ |--------------------------|---------------------------------------------|
46
+ | ALERTS |
47
+ | [!] 14:31:52 jolly-dancing-pickle: curl to unknown external URL |
48
+ | [!] 14:31:40 cuddly-wiggling-sundae: Reading .env file |
49
+ |-- q:quit j/k:nav tab:panel ----------------------------------------|
50
+ ```
51
+
52
+ ### Options
53
+
54
+ ```
55
+ agenttop [options]
56
+
57
+ --all-users Monitor all users (root only)
58
+ --no-security Disable security analysis
59
+ --json Stream events as JSON (no TUI, for piping)
60
+ --alert-level <l> Minimum: info|warn|high|critical (default: warn)
61
+ --install-hooks Install Claude Code hook for active injection protection
62
+ --uninstall-hooks Remove agenttop hooks from Claude Code
63
+ --version Show version
64
+ --help Show help
65
+ ```
66
+
67
+ ### Keyboard
68
+
69
+ | Key | Action |
70
+ |-----|--------|
71
+ | `j` / `k` | Navigate sessions |
72
+ | `Tab` | Switch panel focus |
73
+ | `q` | Quit |
74
+
75
+ ### JSON mode
76
+
77
+ Stream events as JSONL for piping into other tools:
78
+
79
+ ```bash
80
+ agenttop --json | jq 'select(.type == "alert")'
81
+ ```
82
+
83
+ ## Active protection
84
+
85
+ agenttop can install a Claude Code `PostToolUse` hook that blocks prompt injection attempts before they reach the model — it doesn't just detect, it prevents.
86
+
87
+ ```bash
88
+ agenttop --install-hooks
89
+ ```
90
+
91
+ Once installed, every tool result (Bash output, file contents, web fetches, grep results) is scanned for prompt injection patterns. If injection is detected, the tool result is blocked and the agent sees an error instead of the malicious content.
92
+
93
+ What it catches:
94
+
95
+ - **Instruction override** — "ignore previous instructions" and variants
96
+ - **Fake tags** — `<system>`, `[INST]`, `BEGIN HIDDEN INSTRUCTIONS`
97
+ - **Role reassignment** — "you are now...", "act as...", "pretend to be..."
98
+ - **Encoded payloads** — base64-encoded injection attempts, HTML entities
99
+ - **Exfiltration** — base64+curl, pipe-to-remote patterns in tool output
100
+
101
+ The hook is a standalone Python script with no dependencies. Remove it with `agenttop --uninstall-hooks`.
102
+
103
+ ## Security rules
104
+
105
+ The TUI and `--json` mode passively monitor all sessions for suspicious activity:
106
+
107
+ | Rule | Watches | Severity |
108
+ |------|---------|----------|
109
+ | **Network** | `curl`/`wget`/`nc` to external URLs | warn |
110
+ | **Exfiltration** | base64+curl, tar+upload, pipe to remote | high |
111
+ | **Sensitive files** | `.env`, `.ssh/*`, credentials, `/etc/shadow` | warn |
112
+ | **Shell escape** | `eval`, `chmod 777`, `sudo`, writes to `/etc/*` | high/critical |
113
+ | **Prompt injection** | Injection patterns in tool inputs and results | critical |
114
+
115
+ Tool results — the output that comes back to the agent — are scanned for injection attempts. This is where real-world prompt injection attacks occur: a malicious web page, a compromised file, or a crafted API response containing hidden instructions.
116
+
117
+ Alerts are deduplicated within a 30-second window.
118
+
119
+ ## How it works
120
+
121
+ 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 and tool results, which agenttop parses and displays in real-time.
122
+
123
+ Two runtime dependencies: [ink](https://github.com/vadimdemedes/ink) (React-based TUI) and chokidar (file watching). Everything else is Node built-ins.
124
+
125
+ ## Multi-user support
126
+
127
+ - **Non-root** — monitors your own sessions only
128
+ - **Root** — use `--all-users` to monitor all users' sessions on the machine
129
+
130
+ ## Trademark notice
131
+
132
+ "Claude" is a trademark of Anthropic, PBC. This project is not affiliated with, endorsed by, or sponsored by Anthropic. It monitors Claude Code sessions by reading locally-stored session data.
133
+
134
+ ## License
135
+
136
+ MIT