You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`htop` for AI agent fleets. A live terminal dashboard that shows every running Paperclip agent with token burn, cost, current tool, elapsed time, and a kill key.
3
+
Live terminal dashboard for your AI coding sessions. Works with Claude Code today.
|`--refresh-ms`|`2000`| Polling interval in milliseconds |
49
-
|`--alert-level`|`info`| Minimum alert level for Discord: `info`, `warn`, `critical`|
50
-
|`--config`|*optional*| Config file path |
51
-
|`-v, --verbose`|`false`| Enable debug logging to stderr |
52
-
|`--version`| - | Show version and exit |
53
-
|`--help`| - | Show help and exit |
54
-
55
-
### Discord Webhook Alerts
56
-
57
-
agent-htop can post anomaly alerts to Discord when agents exhibit concerning behavior (high spend, error streaks, cost anomalies). This keeps you informed even when the terminal isn't open.
58
-
59
-
#### Setup
60
-
61
-
1. Create a Discord webhook in your server:
62
-
- Right-click the channel → Edit Channel → Integrations → Webhooks → New Webhook
63
-
- Copy the webhook URL
64
-
65
-
2. Set the environment variable and run agent-htop:
|**Paperclip**|`~/.paperclip/instances/default/data/run-logs/<co>/<agent>/`| ✅ Fully supported | NDJSON format with full metrics (tokens, cost, tool calls) |
120
-
|**Claude Code**|`~/.claude/projects/*/`| ✅ Fully supported | JSONL format with session metadata and token usage |
121
-
|**Codex**| TBD | 🔬 Research phase | Format under investigation; stub parser in place for future implementation |
71
+
With Paperclip you also get kill/pause control (`K` / `P` / `R` keys) and agent-level cost tracking.
122
72
123
-
### Using with Claude Code (not Paperclip)
73
+
### Discord webhook alerts
124
74
125
-
If you use Claude Code standalone (without Paperclip), you can still monitor your agent runs. Claude Code logs are stored in `~/.claude/projects/*/` and include session metadata, token usage, and execution details.
75
+
Post anomaly alerts to Discord when agents exhibit high spend, error streaks, or cost spikes:
126
76
127
77
```bash
128
-
# Monitor Claude Code sessions only
129
-
agent-htop --company 920a3930-f429-45cd-8fb8-774fa81cbd96 --runtime claude
Auto-created at `~/.config/agent-htop/config.toml` on first run:
152
106
153
-
Codex support is currently in research phase. A stub parser is in place to document the expected format and provide guidance for future implementation.
# Show HN: agent-htop — Live Terminal Dashboard for AI Agent Fleets
1
+
# Show HN: agent-htop — live terminal dashboard for Claude Code sessions
2
2
3
-
## The Problem
3
+
I was running several Claude Code agents overnight on a side project. Woke up to a larger bill than expected and no quick way to see which session caused it. The logs are buried in `~/.claude/projects/`, costs are scattered across JSON, and there's no live view.
4
4
5
-
I was running 20+ Claude Code agents overnight for a side project. Woke up the next morning to a $40 API bill and no idea which agent caused it. The logs are buried in directories, cost is scattered across JSON, and there's no way to immediately kill a runaway agent without SSH'ing and hunting through processes.
6
-
7
-
## The Solution
8
-
9
-
**agent-htop** is `htop` for your AI agent fleet. A single Go binary that gives you real-time visibility and instant control:
-**Works with Claude Code, Codex, Paperclip** — and single-binary deployment (11MB)
17
+
It's a single Go binary that auto-discovers your Claude Code sessions from `~/.claude/projects/**/*.jsonl` and shows them in a live-updating table. Cost and token counts update in real time as the sessions run.
28
18
29
-
## How It Works
19
+
**Install:**
30
20
31
-
1.`agent-htop --company <id>` — connects to your local Paperclip instance
32
-
2. Live-streams agent status, tokens, cost, and elapsed time
33
-
3. Keyboard control: arrows/vim keys to navigate, `K` to kill, `q` to quit
21
+
```bash
22
+
go install github.com/acunningham-ship-it/agent-htop/cmd/agent-htop@latest
23
+
# or
24
+
brew install acunningham-ship-it/tap/agent-htop
25
+
```
26
+
27
+
**Run:**
34
28
35
-
The binary watches your Paperclip logs in real-time. No API calls needed once it starts (graceful fallback if offline).
29
+
```bash
30
+
agent-htop # no flags needed, finds Claude Code sessions automatically
31
+
```
36
32
37
-
## Why This Matters
33
+
**What it tracks:**
34
+
- Tokens in / out per session
35
+
- Cost in real-time (uses Anthropic's pricing table)
36
+
- Elapsed time and last tool call
37
+
- Anomaly flags for runaway spend or error streaks
38
+
- Optional Discord webhook for alerts when you're not watching
38
39
39
-
AI agents are now as much of an operational liability as they are a feature. If you're running more than one agent in production—especially with Claude—you need visibility into what they're doing and how fast they're burning tokens.
40
+
**Paperclip support (additive):** If you run a Paperclip agent fleet, pass `--company <id>` and your Paperclip agents appear in the same table with kill/pause control (`K` / `P` keys). Otherwise it's purely local file-watching — no API required.
40
41
41
-
This fills that gap.
42
+
Built it as a single Go binary using bubbletea for the TUI. Works on Linux and macOS. The binary is ~11MB.
0 commit comments