agenttop

Real-time terminal dashboard for monitoring AI coding agent sessions — like htop for agents.

Currently supports Claude Code. Reads local session data only — no network requests, no API keys.

Install

npx agenttop

Or install globally:

npm install -g agenttop

Usage

Run agenttop in one terminal while running Claude Code sessions in other tabs.

-- agenttop v0.6.0 ---- 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   |
|   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                  |
|   jolly-dancing-pickle   |                                             |
|   /home/matt/fleet | son |                                             |
|--------------------------|---------------------------------------------|
| ALERTS                                                                 |
| [!] 14:31:52 jolly-dancing-pickle: curl to unknown external URL        |
| [!] 14:31:40 cuddly-wiggling-sundae: Reading .env file                 |
|-- q:quit  j/k:nav  tab:panel  /:filter  n:name  enter:detail ---------|

Options

agenttop [options]

  --all-users          Monitor all users (root only)
  --no-security        Disable security analysis
  --json               Stream events as JSON lines (no TUI)
  --plain              Stream events as plain text (no TUI)
  --alert-level <l>    Minimum: info|warn|high|critical (default: warn)
  --no-notify          Disable all notifications
  --no-alert-log       Disable alert file logging
  --no-updates         Disable update checks
  --poll-interval <ms> Session discovery interval (default: 10000)
  --mcp                Start as MCP server (for Claude Code integration)
  --install-mcp        Register agenttop as MCP server in Claude Code
  --install-hooks      Install Claude Code PostToolUse hook for active protection
  --uninstall-hooks    Remove agenttop hooks from Claude Code
  --version            Show version
  --help               Show this help

Token usage

Each session displays real-time token consumption directly in the session list:

> cuddly-wiggling-sundae
  /home/matt | opus
  CPU 20% | 542MB | 3 ag
  1.2k in | 340 out

Press Enter on a session to see the full breakdown including cache creation, cache read, and cache hit rate percentage.

Session nicknames

Press n on a selected session to assign a nickname. The nickname replaces the slug in the session list and persists across restarts.

Press N to clear a nickname.

Nicknames are stored in ~/.config/agenttop/config.json.

Session filtering

Press / to open the filter input. The filter applies to whichever panel is focused:

Sessions panel — filters by slug, nickname, project, or model
Activity panel — filters by tool name or tool input content

Case-insensitive substring match. Press Esc to clear the filter.

Session management

Delete

Press d to delete a session. A confirmation prompt appears. On confirm, the session's output files are removed from disk and any nickname or archive entry is cleared.

Active/inactive indicators

Sessions with a running process are shown in green. Inactive sessions (no process) are shown in red.

Session detail view

Press Enter on a session to open the detail view, which shows:

Slug, nickname, model, cwd, git branch, version, PID
CPU, memory, uptime, agent count
Full token usage breakdown with cache hit rate

Press Esc or Enter to return to the activity feed.

Split view

Press x to toggle split-screen mode. The right area splits into two independent activity panels, each pinned to a different session with its own scroll position and filter.

When split mode is active:

Pin sessions — navigate to a session in the sidebar and press 1 to pin it to the left panel, or 2 for the right panel
Navigate panels — use Tab or left/right arrows to move focus between sidebar, left panel, and right panel
Independent filtering — press / to filter whichever panel is focused
Swap panels — press S to swap the left and right panels (sessions, scroll, filters)
Close a panel — press X to clear the focused panel's session. If both panels are empty, split mode exits automatically
Detail view — press Enter on a split panel to toggle the detail view for that panel

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.

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.

In the theme menu:

Browse and preview — navigate with up/down arrows. Each theme previews live as you select it
Apply — press Enter to set the selected theme as active
Copy — press c to create a custom theme based on the selected one
Edit — press e to edit a custom theme's colours (individual hex values)
Rename — press r to rename a custom theme
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.

Streaming modes

For piping into other tools or integrating with external systems, agenttop supports two non-TUI streaming modes:

JSON mode

Stream events as JSONL (one JSON object per line):

agenttop --json | jq 'select(.type == "alert")'
agenttop --json --no-security   # tool calls and usage only

Event types: sessions, tool_call, alert, usage.

Plain text mode

Stream events as human-readable lines:

agenttop --plain | grep ALERT
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/
ALERT 14:32:10 [warn] cuddly-wiggling-sundae: curl to external URL
USAGE abc123 +100 in / +50 out

Active protection

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.

agenttop --install-hooks

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.

What it catches:

Instruction override — "ignore previous instructions" and variants
Fake tags — <system>, [INST], BEGIN HIDDEN INSTRUCTIONS
Role reassignment — "you are now...", "act as...", "pretend to be..."
Encoded payloads — base64-encoded injection attempts, HTML entities
Exfiltration — base64+curl, pipe-to-remote patterns in tool output

The hook is a standalone Python script with no dependencies. Remove it with agenttop --uninstall-hooks.

Security rules

The TUI and streaming modes passively monitor all sessions for suspicious activity:

Rule	Watches	Severity
Network	`curl`/`wget`/`nc` to external URLs	warn
Exfiltration	base64+curl, tar+upload, pipe to remote	high
Sensitive files	`.env`, `.ssh/*`, credentials, `/etc/shadow`	warn
Shell escape	`eval`, `chmod 777`, `sudo`, writes to `/etc/*`	high/critical
Prompt injection	Injection patterns in tool inputs and results	critical

Individual rules can be disabled in the config file under security.rules.

Alerts are deduplicated within a 30-second window.

MCP server

agenttop can run as an MCP server, letting Claude Code query session status, alerts, and usage directly:

agenttop --install-mcp   # register in Claude Code settings
agenttop --mcp           # start the MCP server (usually done automatically)

Available tools:

Tool	Description
`agenttop_sessions`	List active sessions with model, CPU, MEM, tokens
`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

You can also run the MCP server directly via agenttop-mcp (installed as a separate bin).

Notifications

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

Rate-limited to max 1 desktop notification per 30 seconds.

Configure in config.json 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.

The log file rotates when it exceeds 10MB (keeps 2 rotated files).

Disable with --no-alert-log or set alerts.enabled: false in config.

Auto-updates

On launch, agenttop checks npm for newer versions (5-second timeout, silent on failure). If a newer version is available, a banner appears in the status bar.

Press u to install the update in the background. Restart to apply.

Background re-checks every 6 hours while running.

Disable with --no-updates or set updates.checkOnLaunch: false in config.

Configuration

Config file at ~/.config/agenttop/config.json (respects XDG_CONFIG_HOME):

{
  "pollInterval": 10000,
  "maxEvents": 200,
  "maxAlerts": 100,
  "alertLevel": "warn",
  "notifications": {
    "bell": true,
    "desktop": false,
    "minSeverity": "high"
  },
  "alerts": {
    "logFile": "~/.config/agenttop/alerts.jsonl",
    "enabled": true
  },
  "updates": {
    "checkOnLaunch": true,
    "checkInterval": 21600000
  },
  "keybindings": {
    "quit": "q",
    "navUp": "k",
    "navDown": "j",
    "panelNext": "tab",
    "panelPrev": "shift+tab",
    "scrollTop": "g",
    "scrollBottom": "G",
    "filter": "/",
    "nickname": "n",
    "clearNickname": "N",
    "detail": "enter",
    "update": "u",
    "settings": "s",
    "archive": "a",
    "delete": "d",
    "viewArchive": "A",
    "split": "x",
    "pinLeft": "1",
    "pinRight": "2",
    "swapPanels": "S",
    "closePanel": "X"
  },
  "theme": "one-dark",
  "customThemes": {},
  "nicknames": {},
  "archived": {},
  "archiveExpiryDays": 0,
  "security": {
    "enabled": true,
    "rules": {
      "network": true,
      "exfiltration": true,
      "sensitiveFiles": true,
      "shellEscape": true,
      "injection": true
    }
  }
}

CLI flags override config values. Config is created with defaults on first run. New fields are auto-populated on upgrade.

Keybindings

All keybindings are configurable via Settings (s). The footer bar updates to reflect your custom bindings.

When rebinding a key, duplicate assignments are rejected with a toast notification — change the conflicting binding first. Press Backspace during rebind to reset a single key to its default, or use Reset all keybindings at the bottom of the keybindings section.

Default keybindings:

Key	Action
`j` / `k` / arrows	Navigate sessions / scroll activity
`Tab` / left / right	Switch panel focus
`Enter`	Open session detail view
`Esc`	Close detail view / clear filter
`/`	Filter active panel (sessions or activity)
`n`	Set nickname for selected session
`N`	Clear nickname
`a`	Archive session (restore in archive view)
`d`	Delete session (with confirmation)
`A`	Toggle archive view
`s`	Open settings
`u`	Install available update
`g` / `G`	Scroll to top / bottom of activity
`x`	Toggle split view
`1` / `2`	Pin session to left / right panel (split mode)
`S`	Swap left and right panels (split mode)
`X`	Close focused panel (split mode)
`q`	Quit

How it works

agenttop reads Claude Code's task output files from /tmp/claude-<uid>/ using inotify-based file watching via chokidar. 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 (React-based TUI), chokidar (file watching), and @modelcontextprotocol/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

Contributing

This project is experimental and contributions are welcome. See CONTRIBUTING.md for development setup, code standards, and PR guidelines.

Ideas for contributions:

Support for additional agent platforms beyond Claude Code
New security rules
Themes and colour customisation
Windows support

Trademark notice

"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.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 61 Commits
.github/workflows		.github/workflows
src		src
tests		tests
.gitignore		.gitignore
.prettierrc		.prettierrc
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.cjs		eslint.config.cjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.cjs		tsup.config.cjs

Folders and files

Latest commit

History

Repository files navigation

agenttop

Table of contents

Install

Usage

Options

Token usage

Session nicknames

Session filtering

Session management

Archive

Delete

Active/inactive indicators

Session detail view

Split view

Themes

Streaming modes

JSON mode

Plain text mode

Active protection

Security rules

MCP server

Notifications

Alert logging

Auto-updates

Configuration

Keybindings

How it works

Multi-user support

Contributing

Trademark notice

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages