Install, usage, what each panel shows, and how ccstatusboard treats your data.
Pick npm or a standalone binary. Both give you the same ccstatusboard command.
Use npm if you have Node 22 or newer. Otherwise use the standalone binary, which needs no Node.
sudo npm i -g ccstatusboard install globally. If your Node comes from nvm, fnm, Volta or Homebrew, leave out sudo: your global directory is already user-owned, and sudo may not find npm.
ccstatusboard after a global install
npx ccstatusboard or try it without installing
curl -fsSL https://raw.githubusercontent.com/areimel/ccstatusboard/main/install.sh | sh
The script downloads the binary for your platform from the latest GitHub Release, verifies its SHA-256 checksum,
and installs it to ~/.local/bin. Make sure that directory is on your PATH.
Override the defaults with environment variables:
| Variable | Meaning | Default |
|---|---|---|
CCSTATUSBOARD_VERSION | Release tag to install (for example v0.2.0) | latest release |
CCSTATUSBOARD_INSTALL_DIR | Directory to install the binary into | ~/.local/bin |
Example:
curl -fsSL https://raw.githubusercontent.com/areimel/ccstatusboard/main/install.sh | CCSTATUSBOARD_INSTALL_DIR=$HOME/bin sh Run ccstatusboard in any terminal. To start with a different theme, add --theme:
ccstatusboard --theme nord npm
sudo npm i -g ccstatusboard@latest standalone binary (re-run the same curl command)
curl -fsSL https://raw.githubusercontent.com/areimel/ccstatusboard/main/install.sh | sh npm
sudo npm rm -g ccstatusboard standalone binary (respects CCSTATUSBOARD_INSTALL_DIR; or just delete the file)
curl -fsSL https://raw.githubusercontent.com/areimel/ccstatusboard/main/install.sh | sh -s -- --uninstall Run it with no arguments, or pass any of these flags.
ccstatusboard [options]| Flag | What it does |
|---|---|
--theme <name> | Start theme; t / T cycle and save it (see below) |
--refresh <ms> | UI refresh interval (default 1000, minimum 250) |
--ended-hours <n> | Keep ended sessions for n hours (default 0: removed when they exit) |
--sort <key> | project (default), status, activity, cost, ctx or name |
--claude-dir <path> | Claude Code config dir (default $CLAUDE_CONFIG_DIR, else ~/.claude) |
--no-usage-api | Do not call the Anthropic usage API (limits show "disabled") |
--config <path> | Config file path (default ~/.config/ccstatusboard/config.json) |
-v, --version | Print version |
-h, --help | Print help |
Press t or T to cycle themes. Your choice is saved to the config file. Or start with --theme <name>.
Press Esc outside search to open it. Use ↑ ↓ to move,
← → to change a value, Enter to edit numbers and column visibility,
and Esc to close. Changes apply immediately and are written to
~/.config/ccstatusboard/config.json.
| Option | Config key | Default |
|---|---|---|
| Theme | theme | default |
| Subscription price (per month, for plan ratio) | subscriptionUSD | unset |
| Sort | sort | project |
| Detail pane | showDetail | on |
| System panel | showSystem | on |
| System metrics | systemMetrics | all groups |
| Columns | columns | all but branch |
| Dim idle after | idleCutoffMinutes | 60 min (1h) |
| Keep exited | endedWindowHours | 0 (removed on exit) |
| Refresh | refreshMs | 1000 ms |
| Usage poll | usagePollSeconds | 60 s |
The full config reference is in the README on GitHub.
Each panel of the board, with what it shows and the details behind it.
Shows how much of your 5-hour and weekly Claude usage you have used, and when each limit resets.
5h [|||||||||||| ] 58% resets 2h14m Week [|||||| ] 31% resets Thu 09:00
Projects where each limit will end up at its reset.
5h NEAR LIMIT 92% at reset hits n/a Week OVER 108% at reset hits Wed
Shows estimated spend in USD for the current block, today, this week and this month.
block $12.40 week $96.10 month $412.75 burn $4.10/h 24h ▁▂▃▅▇▆▅▃▂▃▅▆▇▅▃▂▁▁▂▃▅▆▇▆
Lists every Claude Code session on this machine, grouped by project.
── ccstatusboard (1) ────────────────── ◐ ccstatusboard opus-5.5 ███████░░░ 61% $4.20 now ├─ Explore 12s ○ power-tools sonnet ██░░░░░░░░ 22% $1.10 3m
Shows CPU, memory, swap and disk usage, plus network activity, at a glance.
cpu [||||||| ] 34% mem [|||||||||| ] 52% net ▁▂▃▅▂▁▁▃▅▇▅▃ down ▁▁▂▁▁▂▁▃▁▁▂▁ up
Shows the full details for the selected session.
tokens in 182k out 41k cache 1.9M cost opus-5.5 $4.20 agents Explore cwd ~/code/ccstatusboard
ccstatusboard runs locally. It makes two kinds of network request, and you
can switch the usage one off with
--no-usage-api.
| Data | Source |
|---|---|
| Running sessions and status | ~/.claude/sessions/<pid>.json, checked against the live process table |
| Project name | git rev-parse --git-common-dir in each session's cwd (read-only; falls back to the folder name outside a git repo) |
| Subagents | The session's subagents/ folder: agent transcripts, and which agents wrote recently (active ones only) |
| Tokens, model, branch, context | Session transcripts in ~/.claude/projects/**/*.jsonl (tailed incrementally) |
| Today / week / month totals | A startup scan of transcripts from the last 35 days, cached in ccstatusboard's cache dir |
| 5h / weekly limits | Anthropic's OAuth usage endpoint (as used by Claude Code's /usage), polled every 60 s |
| Prices | LiteLLM's pricing table (https://github.com/BerriAI/litellm), cached for 24 h |
| CPU, memory, swap, disk, net, load | /proc on Linux, sysctl and netstat on macOS; disk via statfs. Sampled every 2 s, with 60 points of history for the sparklines |
| Per-session CPU and memory | /proc/<pid>/stat and statm on Linux; ps on macOS, for the live session processes only |