# Add to your Claude Code skills
git clone https://github.com/ldegio/agtop
README.md
agtop
Run with:
npx @ldegio/agtop
Your window into what your AI coding agents are doing, sitting in the terminal, where you run them. agtop is a top-style terminal dashboard that tracks every Claude Code and Codex session on your machine: spend, token usage, context pressure, CPU load, tool invocations, and more. All in one place, live.
Features
Session discovery -- automatically finds Claude Code (~/.claude/projects/) and Codex (~/.codex/sessions/) sessions
Cost tracking -- per-session spend with hourly and daily breakdowns; plan-aware billing (retail, Max, included)
Context pressure -- CTX% shows how full each agent's context window is
Live toggle -- filter to running sessions with real-time CPU%, cost rates, and incremental tool counts
Performance panel -- per-session CPU and memory sparkline charts over time
Processes panel -- live process tree showing child processes with CPU%, memory, and command lines
Tool Activity panel -- scrollable per-tool invocation history with timestamps; see exactly what each agent has been doing
Cost panel -- total spend by time window with per-model token and cost breakdown
Config panel -- browse CLAUDE.md/AGENTS.md, memories, skills, MCP servers, and permissions per session
OS process metrics -- CPU% and PID count for running sessions (macOS/Linux/Windows)
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
| Flag | Description |
|------|-------------|
| -l, --list | List sessions in a table and exit |
| -j, --json | Dump full session data as JSON and exit |
| -p, --plan <plan> | Billing plan for cost display (default: retail) |
| -d, --delay <secs> | Refresh interval in seconds (default: 2) |
| -h, --help | Show help |
Keyboard Shortcuts
| Key | Action |
|-----|--------|
| j/k or arrows | Navigate sessions |
| Enter | Open detail view |
| Tab | Cycle bottom panel tabs |
| Shift+Tab or ` | Toggle Live filter |
| 1-6 | Switch to Info/Performance/Processes/Tool Activity/Cost/Config panel |
| F1, ?, h | Show help |
| F3 or / | Search/filter sessions |
| F5 or r | Force refresh |
| F6 or > | Sort-by panel |
| F7 | Filter sessions by age (1d/1w/1mo) |
| P/M/T | Sort by Status/Memory/Cost |
| d | Delete selected session (non-running only) |
| q or F10 | Quit |
JSON Output
agtop -j dumps comprehensive session data including:
Activity metrics (tool invocations by name, skills, web fetches/searches, MCP calls)
Screenshots
Info panel: session identity, wall/API time, context pressure
Performance: per-session CPU and memory sparkline charts over time
Processes: live process tree with CPU%, memory, and command lines (C++ builds, caffeinate, etc.)
Tool Activity: per-tool invocation counts and live feed with timestamps
Cost breakdown: total spend by time window, per-model token and cost split
Config: browse CLAUDE.md, memories, skills, MCP servers, and permissions
How It Works
agtop reads JSONL transcript files written by Claude Code and Codex to extract token counts, tool invocations, and model information. It fetches current model pricing from LiteLLM (cached for 24 hours) to compute cost estimates. For running sessions, it uses ps and lsof to map OS processes back to sessions and collect CPU/memory metrics.
A Claude Code plugin that automatically captures everything Claude does during your coding sessions, compresses it with AI (using Claude's agent-sdk), and injects relevant context back into future sessions.
