ccdash

iad-ci

A lightweight terminal dashboard for Claude Code and Codex CLI — shows token usage, cost, agent session status, and system resources in real time.

Built with Bubble Tea.

Token panel — aggregates usage from Claude Code's JSONL logs in ~/.claude/projects and Codex rollout logs in ~/.codex/sessions/YYYY/MM/DD. Displays input, output, and cache tokens; total cost; tokens/min rate; and a per-model cost breakdown, color-coded and sorted by spend.

Session panel — shows active Claude Code and Codex agent sessions and their current state. Hook-tracked sessions carry a Claude 🤖 or Codex 💻 badge:

Session tracking has two modes: tmux pane inspection (automatic) and hook-based tracking (more accurate). Install Claude hooks with ccdash --install-hooks or Codex hooks with ccdash --install-codex-hooks.

System panel — CPU, memory, swap, disk, network I/O, and load average via gopsutil.

Download the latest release from the releases page, make it executable, and move it to your PATH.

Requires Go 1.21+.

go install github.com/jedarden/ccdash/cmd/ccdash@latest

git clone https://github.com/jedarden/ccdash.git
cd ccdash
make install

ccdash

Press l to change how far back the token panel looks:

• Monday 9am (default — useful for weekly work tracking)
• Today
• Last 24h / 7d / 30d / All time
• Custom date and time (navigate with arrow keys)

ccdash automatically adjusts to your terminal width:

• Narrow (< 120 cols): panels stacked vertically
• Wide (120–239 cols): two panels on top, one below
• Ultra-wide (≥ 240 cols): three panels side by side

For accurate Claude per-session status (especially the WORKING/ASKING distinction), install Claude Code hooks:

ccdash --install-hooks

This writes hook scripts that fire on Claude Code lifecycle events, writing session state to ~/.ccdash/sessions/. The dashboard reads those files alongside the tmux pane inspection — hook data takes precedence when available.

For Codex CLI, install its equivalent status-only hooks with:

ccdash --install-codex-hooks

This adds SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse, PermissionRequest, and Stop entries to ~/.codex/hooks.json. Token counts are read from rollout JSONL, not hook payloads. Use ccdash --check-hooks to inspect either harness and ccdash --uninstall-hooks to remove ccdash entries from both.

Check whether hooks are installed:

ccdash --check-hooks

By default, ccdash scans ~/.claude/projects for all JSONL usage files. To include additional project root directories:

# Via flag (comma-separated)
ccdash --extra-dirs /path/to/projects,/other/path
# Via environment variable (colon-separated)
CCDASH_EXTRA_DIRS=/path/to/projects:/other/path ccdash

Token data is persisted to ~/.ccdash/tokens.db (SQLite). You can query it directly with sqlite3 or DuckDB:

sqlite3 ~/.ccdash/tokens.db "SELECT model, SUM(total_tokens), SUM(cost) FROM token_events GROUP BY model;"

ccdash/
├── cmd/ccdash/ # Entry point, CLI flags
├── internal/
│ ├── metrics/ # Collectors: system, tokens (JSONL + SQLite), tmux, hooks
│ └── ui/ # Bubble Tea dashboard model and panels
└── Makefile

make build # Build binary to ./bin/ccdash
make test # Run tests
make deps # Download dependencies
make clean # Remove build artifacts

• Go 1.21+
• ~/.claude/ directory (Claude Code data; created automatically when you use Claude Code)
• ~/.codex/ directory (Codex CLI data; created automatically when you use Codex)
• tmux (optional, for session panel)

Apache-2.0 — see LICENSE.

Part of jedarden.com · Read the write-up: jedarden.com/projects/ccdash/

This GitHub repo is a read-only mirror of git.ardenone.com/jedarden/ccdash — issues and PRs are welcome here either way.