Stop Flying Blind: Monitor AI Coding Agents with agtop

You're burning through API credits and you don't even know where they're going. That claude process spinning in your terminal? It's silently racking up dollars while you grab coffee. The Codex session you left running overnight? It might have invoked tools 847 times, cached half the internet into context, and pushed your context window to 94%—but you'd never know until the bill arrives.

Here's the dirty secret about AI coding agents in 2024: they're black boxes with expensive appetites. We obsess over prompts and models, yet we monitor these autonomous systems with all the sophistication of a developer squinting at top and guessing. No cost visibility. No context pressure awareness. No insight into what tools your agent actually invoked or whether that C++ build process is consuming 400% CPU because of a runaway compilation.

What if you could peer inside every Claude Code and Codex session on your machine—in real time, in your terminal, with the same immediacy that htop brought to process monitoring?

Meet agtop, the open-source TUI that transforms AI agent observability from an afterthought into a first-class terminal experience. Created by Loris Degioanni, agtop is rapidly becoming the essential tool developers didn't know they desperately needed. And the kicker? It runs with a single command—no installation required.

What Is agtop?

agtop is a top-style Terminal User Interface (TUI) purpose-built for monitoring AI coding agent sessions. Think of it as htop meets CloudWatch, but designed specifically for the unique telemetry that Claude Code and Codex generate—running locally in your terminal where you already work.

The tool was developed by Loris Degioanni, a name that carries serious weight in systems observability (he's the creator of Sysdig and Falco). This pedigree shows: agtop isn't a hastily thrown-together script. It's a thoughtfully engineered monitoring layer that understands both the behavior of AI agents and the infrastructure they run on.

Why it's trending now: We're in the middle of an agentic coding explosion. Claude Code, OpenAI's Codex CLI, and similar tools are moving from experiments to daily drivers for thousands of developers. But our tooling hasn't caught up. We monitor traditional services with Prometheus and Grafana, yet our most expensive and unpredictable compute—autonomous AI agents—runs with zero visibility. agtop fills this critical gap at exactly the right moment.

The project is open-source under GPL v2, requires only Node.js 18+, and has zero runtime dependencies. That minimal footprint is intentional: it installs anywhere, runs instantly, and never becomes its own infrastructure burden.

Key Features That Expose Everything

agtop's feature set reveals how deeply its creator understands the AI agent lifecycle. This isn't surface-level monitoring—it's comprehensive observability across six dimensions:

Automatic Session Discovery

No configuration files to maintain, no manual session registration. agtop automatically discovers Claude Code sessions in ~/.claude/projects/ and Codex sessions in ~/.codex/sessions/ by reading the JSONL transcript files these tools write. The moment you start an agent, agtop sees it.

Precision Cost Tracking

This is where agtop pays for itself immediately. Per-session spend with hourly and daily breakdowns, plan-aware billing (retail, Max, included tiers), and per-model token cost splits. No more surprise $50 sessions because you didn't realize Claude 3.7 Sonnet costs 3x more than Haiku for your use case.

Context Pressure Monitoring

The CTX% metric is genius—literally. It shows how full each agent's context window is, in real time. Hitting 90%+ context pressure? That's your signal to start a fresh session, summarize work, or expect degraded performance and spiraling costs.

Live Performance Intelligence

Toggle the Live filter (Shift+Tab or backtick) to focus on running sessions with real-time CPU%, cost rates, and incremental tool counts. The Performance panel renders sparkline charts for CPU and memory over time. The Processes panel displays a live process tree—child processes, CPU%, memory, command lines. You'll spot that runaway caffeinate process or C++ compilation storm instantly.

Tool Activity Forensics

The Tool Activity panel is a scrollable, timestamped history of every tool invocation. This is audit-trail level visibility: exactly what did your agent do, when, and how often? Combined with the Cost panel's time-windowed spend analysis and the Config panel's browsing of CLAUDE.md, memories, skills, MCP servers, and permissions—you have complete operational awareness.

Multi-Modal Interaction

Full mouse support: click to select, sort by column, switch tabs, hover for tooltips. But also comprehensive keyboard shortcuts for terminal purists. And non-interactive modes (-l for table, -j for JSON) for scripting and CI/CD integration.

Use Cases: Where agtop Transforms Your Workflow

1. The Credit Burn Discovery

You've been experimenting with Claude Code for a week. The bill arrives: $340. With agtop, you replay the session history, discover that one long-running session with heavy context pressure cost $89 alone, and identify that repeated Read tool invocations on a large codebase were the culprit. Next week, you structure your sessions differently and cut costs by 60%.

2. The Runaway Agent Rescue

It's 2 AM. Your Codex agent is "still working." You SSH in, fire up agtop, and see: 97% context pressure, CPU pinned at 380%, a child node process consuming 4GB RAM, and the Bash tool has been invoked 2,000 times in a loop. You kill the session before it racks up another $20 and melts your VPS.

3. The Team Cost Accountability

Your startup has five developers using Claude Code. Finance wants visibility. You run agtop -j in a cron job, pipe JSON to your existing monitoring stack, and suddenly have per-developer, per-project, per-model cost attribution. No new infrastructure—agtop becomes your data source.

4. The Performance Optimization Loop

You're choosing between Claude 3.5 Sonnet and 3.7 Sonnet for a refactoring task. agtop's side-by-side comparison—tokens per hour, context efficiency, tool invocation patterns—gives you empirical data for model selection, not vendor marketing.

5. The Compliance Audit

Your security team needs to know what AI agents accessed. agtop's tool activity logs, MCP server configurations, and permission browsing provide the forensic trail that satisfies auditors without building custom logging pipelines.

Step-by-Step Installation & Setup Guide

Zero-Friction First Run (No Installation)

The fastest way to experience agtop—literally seconds:

# Run directly without installation
npx @ldegio/agtop

This downloads and executes the latest version. Perfect for evaluation, CI environments, or machines where you don't want global packages.

Permanent Installation

For daily use, install globally so agtop is always available:

# Install globally via npm
npm install -g @ldegio/agtop

# Launch the TUI
agtop

# Remove when no longer needed
npm uninstall -g @ldegio/agtop

System Requirements

Verify your Node version before installing:

node --version
# Should output v18.0.0 or higher

Configuration & Options

agtop works out of the box, but command-line flags customize behavior:

# List sessions as table, then exit (scripting-friendly)
agtop -l

# Dump full JSON for external processing
agtop -j > agent-sessions-$(date +%Y%m%d).json

# Use Max plan pricing for cost calculations
agtop --plan max

# Slower refresh for remote/SSH sessions
agtop --delay 5

REAL Code Examples from the Repository

Example 1: Basic Invocation and Navigation

The simplest entry point—run without installation, then navigate with vim-style keys:

# Execute agtop directly from npm registry
npx @ldegio/agtop

Once running, the TUI presents a live session list. Navigate with:

# Keyboard navigation (vim-style or arrow keys)
j / k         # Move down/up between sessions
Enter         # Open detailed view for selected session
Tab           # Cycle through bottom panel tabs
` / Shift+Tab # Toggle Live filter (running sessions only)
q / F10       # Quit

Why this matters: The npx execution model eliminates friction entirely. No package.json to manage, no version pinning debates, no global namespace pollution. For teams standardizing on agtop, the global install (npm install -g) provides the agtop command everywhere. The dual navigation system—vim keys for terminal natives, arrows for everyone else—shows thoughtful UX design.

Example 2: Non-Interactive JSON Export for Automation

Extract comprehensive session data for programmatic analysis:

# Export all session data as structured JSON
agtop -j

# Typical output structure includes:
# - Session identity (provider, ID, project, model)
# - Cost breakdown (total, per-category, hourly/daily rates)
# - Token counts (input, output, cached, detailed splits)
# - Activity metrics (tool invocations, skills, web fetches, MCP calls)

Practical implementation pattern—nightly cost reporting:

#!/bin/bash
# save as: /usr/local/bin/agent-cost-report.sh

REPORT_FILE="/var/log/agtop/cost-report-$(date +%Y-%m-%d).json"

# Ensure directory exists
mkdir -p "$(dirname "$REPORT_FILE")"

# Generate JSON report
agtop -j > "$REPORT_FILE"

# Extract total daily spend using jq (install separately)
DAILY_TOTAL=$(jq '[.sessions[].cost.total] | add' "$REPORT_FILE")

echo "Daily AI agent spend: \$${DAILY_TOTAL}"
echo "Full report: $REPORT_FILE"

Why this matters: The -j flag transforms agtop from an interactive tool into a data source. The JSON schema is comprehensive—session identity, granular cost breakdowns, token splits by type, and activity metrics. This enables integration with existing observability stacks: pipe to Datadog, store in S3 for Athena queries, or trigger PagerDuty alerts when daily spend exceeds thresholds.

Example 3: Custom Refresh Interval for Remote Monitoring

Optimize agtop for bandwidth-constrained or high-latency connections:

# Slow refresh to 5 seconds for SSH over slow VPN
agtop --delay 5

# Or use short flag
agtop -d 5

Advanced pattern—tmux sidecar for persistent monitoring:

# Create dedicated tmux window for agent monitoring
tmux new-window -n 'agents' 'agtop -d 3'

# From another tmux window, your main work continues
# Glance at agent status without context switching

Why this matters: The default 2-second refresh is aggressive for local use but wasteful over SSH. The configurable delay makes agtop viable for remote server monitoring—watch agents on your production build machine from your laptop. Combined with tmux or screen, it becomes a persistent operational dashboard, always visible in a dedicated terminal pane.

Example 4: Plan-Aware Cost Calculation

Accurate cost modeling requires correct billing tier:

# Default: retail pricing (pay-as-you-go)
agtop --plan retail

# Anthropic Max plan (different rate structure)
agtop --plan max

# Included/enterprise allocation (show usage against quota)
agtop --plan included

Implementation insight: agtop fetches current model pricing from LiteLLM (cached for 24 hours) to compute estimates. The plan flag adjusts which rate card applies. For organizations with negotiated enterprise pricing, the included mode tracks consumption against prepaid allocations—critical for budget management.

Advanced Usage & Best Practices

Keyboard Mastery for Speed

Memorize these power-user shortcuts to eliminate mouse dependency:

Context Pressure Management

CTX% above 85% is your warning threshold. When you see this:

• Start a fresh session with summarized context
• Use /clear or equivalent in your agent
• Expect degraded response quality and higher costs per request

Cost Optimization Workflow

1. Run agtop in Live mode during active development
2. Identify highest-cost sessions with T sort
3. Drill into Cost panel (5) for model/token breakdown
4. Switch to Tool Activity (4) to identify expensive patterns
5. Adjust your prompting or session structure accordingly

Automation Integration

# Cron job: daily cost snapshot at midnight
0 0 * * * /usr/local/bin/agtop -j > /backups/agtop/$(date +\%Y\%m\%d).json

# Alert script: notify if any running session exceeds $10/hour
agtop -j | jq '.sessions[] | select(.cost.hourly > 10) | .id' | \
  xargs -I {} notify-send "Expensive agent session: {}"

Comparison with Alternatives

Why agtop wins: Alternatives force a choice between convenience and capability. Native system tools lack AI context entirely. Cloud dashboards require account setup, have latency, and rarely expose terminal-level detail. Custom scripts demand maintenance burden. agtop uniquely combines instant availability, AI-native semantics, and terminal-native UX in a zero-dependency package.

FAQ: Common Developer Concerns

Does agtop work with custom Claude Code installations?

Yes. agtop discovers sessions by reading JSONL transcript files from standard paths (~/.claude/projects/). If your installation uses custom paths, symlink or mount the directory to the expected location.

How accurate are the cost estimates?

agtop fetches current pricing from LiteLLM (cached 24 hours) and applies your selected plan (retail/max/included). Estimates are typically within 1-2% of actual billing, with variance from caching, promotional credits, or regional pricing differences.

Can I monitor remote servers?

Absolutely. Run agtop via SSH, or use -j with --delay for bandwidth-efficient monitoring. For persistent remote dashboards, combine with tmux or deploy a small JSON-export pipeline to your central observability stack.

Is my session data sent anywhere?

No. agtop operates entirely locally. It reads transcript files from your filesystem and uses ps/lsof for process metrics. The only external call is to LiteLLM for pricing data—no session content, tokens, or usage patterns leave your machine.

What about other AI coding agents?

Currently optimized for Claude Code and Codex. The architecture supports extension—transcript parsers for Aider, Continue, or other agents would follow the same JSONL-reading pattern. Contributions welcome on GitHub.

How do I contribute or report issues?

Visit github.com/ldegio/agtop. The GPL v2 license encourages forks and improvements. Bug reports with agtop -j output are especially valuable for reproduction.

Will this slow down my agents?

Negligible impact. agtop is a read-only observer—it parses existing transcript files and queries OS process tables. No instrumentation, no hooks, no agent modification. Typical CPU usage: <1% of a single core.

Conclusion: See What You've Been Missing

We've entered the era of autonomous coding agents that write, test, and deploy code while we sleep. But autonomy without observability is just expensive gambling. Every unexplained spike in your Anthropic invoice, every agent that "seemed fine" until it wasn't, every context window silently filling to capacity—these are symptoms of a monitoring gap that agtop closes with elegant precision.

This isn't about micromanaging AI. It's about operational maturity. We don't deploy microservices without metrics; we shouldn't deploy cognitive workers without equivalent visibility. agtop gives you that visibility in the environment you already inhabit—your terminal—with the immediacy that terminal tools uniquely provide.

The single-command execution (npx @ldegio/agtop) removes every excuse for not trying it. The zero-dependency, cross-platform design means it works everywhere you do. And the open-source GPL v2 license ensures it remains a community asset, not a vendor lock-in.

My take? In six months, monitoring AI agents will be as standard as git status. Early adopters of agtop are building the operational muscle memory that will define best practices for this new computing paradigm. The developers who understand their agents' behavior—cost patterns, context efficiency, tool usage—will build more effectively and spend dramatically less.

Stop flying blind. Install agtop today, run that first npx @ldegio/agtop, and prepare for the uncomfortable revelation of what your agents have actually been doing all this time.

Found this valuable? Star the repository, share with your team, and join the growing community of developers who refuse to treat AI agents as unobservable black boxes.