aitop 0.4.0

btop for AI — terminal dashboard for token usage and costs
Documentation

aitop

License: MIT

btop for AI — a terminal dashboard for monitoring AI token usage, costs, and sessions.

Dashboard

Like btop monitors your system resources, aitop monitors your AI spend. Built for developers who live in the terminal and want to keep an eye on their Claude Code, Gemini CLI, and OpenClaw costs without leaving it.

Sessions

Sessions

Trends

Trends

Features

  • Live TUI dashboard with btop-style keyboard shortcuts and highlighted shortcut letters
  • 4 views: Dashboard, Sessions, Models, Trends — switch with d/s/m/t
  • Multi-provider — reads Claude Code, Gemini CLI, and OpenClaw session files
  • Zero auth required — reads local session files directly, no API keys needed
  • SQLite-backed — indexes once, instant startup after first run
  • Live file watching — detects new session data in real-time with fs watcher
  • Burn rate tracking — see your $/hr, daily spend, weekly totals at a glance
  • Budget gauge — visual progress bar with color thresholds when budget is configured
  • Model breakdown — cost, tokens, and cache hit ratio per model
  • Session explorer — sortable table with inline sparklines, filter/search, and drill-down detail popup
  • Delta banner — shows cost/token changes since your last check
  • Spend trends — daily cost chart with projections, heatmap, and contribution calendar
  • Project cost attribution — cost breakdown by project
  • Token efficiency score — tokens per dollar, cache savings metrics
  • 6 color themes — ember (default), nord, dracula, gruvbox, catppuccin, mono — cycle with p
  • 3MB single binary, zero runtime dependencies, zero network calls

Install

Homebrew (macOS & Linux)

brew install bugkill3r/aitop/aitop

Shell installer

curl -fsSL https://raw.githubusercontent.com/bugkill3r/aitop/master/install.sh | sh

Cargo

cargo install aitop

GitHub Releases

Download prebuilt binaries from the Releases page.

macOS note: Unsigned binaries may trigger Gatekeeper. Run xattr -d com.apple.quarantine aitop after downloading.

Build from source

git clone https://github.com/bugkill3r/aitop.git
cd aitop
cargo build --release
./target/release/aitop

Usage

# Launch TUI dashboard
aitop

# Quick table output (non-interactive)
aitop --light

# Choose a theme
aitop --theme dracula

# Custom refresh rate (seconds)
aitop --refresh 5

Keyboard Shortcuts

Key Action
d Dashboard view
s Sessions view
m Models view
t Trends view
1-4 Quick switch views
j/k or ↑/↓ Navigate tables
Enter Open session detail popup
Esc Close popup / dismiss banner
/ Filter sessions by project
c/n/o/u Sort by cost/tokens/project/recent
a Toggle sort ascending/descending
w/W/A Trend range: week/month/all
p Cycle color theme
r Force refresh
? Help overlay
q Quit

How It Works

aitop reads session files from multiple AI coding tools and indexes them into a local SQLite database:

Provider Data Location Format
Claude Code ~/.claude/projects/ JSONL
Gemini CLI ~/.gemini/tmp/ JSON
OpenClaw ~/.openclaw/agents/ JSONL

Token costs are computed using built-in pricing (extensible via config). The database is incrementally updated — only new data is parsed on subsequent runs. Zero network calls.

Configuration

Config file at ~/.config/aitop/config.toml:

refresh = 2          # Refresh interval in seconds
theme = "ember"      # Color theme
# weekly_budget = 200.0  # Optional budget gauge

# Custom model pricing (per million tokens)
# [model_pricing."some-future-model"]
# input = 5.0
# output = 25.0
# cache_read = 0.50
# cache_creation = 6.25

Model pricing is extensible — built-in pricing covers Claude (Opus, Sonnet, Haiku), Gemini, and OpenAI models. Add or override pricing for any model via config.

Contributing

See CONTRIBUTING.md for development setup, testing, and PR guidelines.

Tech Stack

Rust, Ratatui, Crossterm, SQLite (rusqlite), notify (fs watcher), Tokio

License

MIT