uppinote20/claude-dashboard

Comprehensive status line plugin for Claude Code with context usage, API rate limits, and cost tracking

TypeScript

579

527 commits

updated Oct 6, 2026

claude-dashboard.uppinote.dev

See the code

See what people are saying

Newest first

Most points

Source	Message	Score	Date
	My Claude Code status line now runs as a mod, so I can finally see my limits in the desktop app (r/ClaudeAI) https://preview.redd.it/op31ig1rmxth1.png?width=2210&format=png&auto=webp&s=013fe2037cbcfe679517bf226305e6d83f75609f I've been building claude-dashboard, a status line plugin for Claude Code, since January. It shows context %, session cost, and the 5h / 7d limits with a countdown to…	0	Oct 6, 2026

README

claude-dashboard

License Stars

Comprehensive status line plugin for Claude Code — unified usage monitoring across Claude, Codex, Gemini, Antigravity, and z.ai CLIs, with context, rate limits, cost tracking, and a modular widget system.

Demo

Installation

Requirements: Claude Code v1.0.80+ / Node.js 18+

From Plugin Marketplace

/plugin marketplace add uppinote20/claude-dashboard
/plugin install claude-dashboard
/claude-dashboard:setup

Manual Installation

git clone https://github.com/uppinote20/claude-dashboard.git "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/claude-dashboard"
/claude-dashboard:setup

/claude-dashboard:setup looks for the plugin under plugins/cache/claude-dashboard/claude-dashboard/, which a manual clone into plugins/claude-dashboard/ does not match — the setup command's shim lookup will find nothing to copy. Point statusLine.command in settings.json directly at your clone's dist/index.js instead (e.g. node "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/claude-dashboard/dist/index.js"), and note that manual installs do not get automatic version pickup — git pull and update the path yourself after each release.

Display Modes

Compact (1 line) - Default:

Compact

Model, context progress bar, cost, rate limits (5h/7d) or z.ai usage (mutually exclusive by provider)

Normal (2 lines):

Normal

Adds project info, session ID, session duration, burn rate, todo progress

Detailed (6 lines):

Detailed

Adds depletion time, config counts, tool/agent status, cache hit, performance badge, token breakdown, forecast, budget, Codex/Gemini/Antigravity usage

Multi-provider support: z.ai/ZHIPU, Codex, Gemini, Antigravity auto-detected when installed.

Widgets

Category	Widget	Description
Core	`model`	Model name and version with emoji (e.g. `Opus 5.5`), effort level for Opus/Sonnet/Fable (MAX/X/H/M/L), fast mode for Opus (↯). Reads the live `effort.level` / `fast_mode` from stdin, falling back to `settings.json` on older Claude Code
	`context`	Progress bar, percentage, tokens (🟢 0-50% / 🟡 51-80% / 🔴 81-100%)
	`contextBar`	Progress bar only (sub-widget of `context`)
	`contextPercentage`	Percentage only (sub-widget of `context`)
	`contextUsage`	Token count only, e.g. `42K/200K` (sub-widget of `context`)
	`cost`	Session cost in USD
	`projectInfo`	Directory + git branch (clickable OSC8 link) + ahead/behind (↑↓), subpath from project_dir, worktree indicator (🌳)
Rate Limits	`rateLimit5h`	5-hour rate limit with reset countdown
	`rateLimit7d`	7-day rate limit (Pro and Max)
	`rateLimit7dSonnet`	7-day Sonnet limit (Max only) — deprecated ~2026-06: Anthropic merged it into the unified weekly bucket at the Sonnet 5 launch, so the API returns `null` and the widget stays hidden until/unless the field returns
	`rateLimit7dFable`	7-day Fable limit (Max only)
Session	`sessionId`	Session ID (short 8-char)
	`sessionIdFull`	Session ID (full UUID)
	`sessionName`	Session name from /rename command
	`sessionDuration`	Session duration
	`lastPrompt`	Last user prompt with timestamp
	`configCounts`	CLAUDE.md, AGENTS.md, rules, MCPs, hooks, +Dirs
Activity	`toolActivity`	Running/completed tools with targets (e.g., `Read(app.ts)`)
	`agentStatus`	Subagent progress with resolved model, e.g. `Explore(Opus)` (from the Agent tool's `model` param or `CLAUDE_CODE_SUBAGENT_MODEL`)
	`todoProgress`	Todo completion rate
Analytics	`burnRate`	Token consumption per minute, session average (input + cache write + output)
	`cacheHit`	Cache hit rate percentage (last request)
	`promptCache`	Session prompt-cache health: ♨️ warm with time left before it goes cold / ❄️ cold, hit ratio, miss count, e.g. `♨️ 4m 91% miss 2` (from `prompt_cache`, Claude Code ≥ 2.1.251). The warm→cold switch happens on its own; set `statusLine.refreshInterval` (e.g. `60`) to keep the minute countdown ticking while idle
	`promptCacheState`	Warm/cold icon + time left only, e.g. `♨️ 4m` (sub-widget of `promptCache`)
	`promptCacheHit`	Session cache hit ratio only, e.g. `91%` (sub-widget of `promptCache`)
	`promptCacheMisses`	Miss count only, e.g. `miss 2`; hidden at 0 (sub-widget of `promptCache`)
	`depletionTime`	Estimated time to rate limit (approx)¹
Multi-CLI	`codexUsage`	OpenAI Codex CLI usage (auto-hide if not installed)²
	`geminiUsage`	Google Gemini CLI - current model (auto-hide if not installed)³
	`geminiUsageAll`	Google Gemini CLI - all models (auto-hide if not installed)³
	`antigravityUsage`	Google Antigravity CLI - weekly quota by model family (auto-hide if not installed)⁸
	`antigravityUsageAll`	Google Antigravity CLI - per-model quota (auto-hide if not installed)⁸
	`zaiUsage`	z.ai/ZHIPU usage (auto-hide if not using z.ai)⁴
Insights	`tokenBreakdown`	Input/output/cache write/read token breakdown
	`performance`	Composite efficiency badge (cache hit + output ratio)
	`forecast`	Estimated hourly cost based on session rate
	`budget`	Daily spending vs configured budget limit⁵
	`tokenSpeed`	Output token generation speed (tok/s), session average
	`tokenSpeedLast`	Output token generation speed of the most recent response only
	`todayCost`	Total spending across all sessions today
Status	`peakHours`	Peak hours indicator with countdown (based on PeakClaude)⁶
	`tagStatus`	Commits ahead of matched git tags (default pattern `v*`, customize via `tagPatterns`)⁷
	`slashCommand`	Active slash command for the current turn (🎯), cleared by next plain-text message
	`agentMode`	Session agent identity: 👤 custom agent (via `/agent <name>`) or 🤖 subagent type
Info	`linesChanged`	Uncommitted lines added/removed, including untracked files (+N -N)
	`outputStyle`	Current output style (hidden when "default")
	`version`	Claude Code version display
	`vimMode`	Vim mode (NORMAL/INSERT), auto-hides when vim disabled
	`apiDuration`	API time as % of total session time

¹ Assumes all utilization came from this session; improves as session runs longer. ² Auto-hides if ~/.codex/auth.json not found. ³ Auto-hides if ~/.gemini/oauth_creds.json not found — Gemini CLI personal tiers were retired 2026-06-18 in favor of Antigravity CLI (enterprise still supported). ⁴ Auto-hides if not detected via ANTHROPIC_BASE_URL. ⁵ Requires "dailyBudget" in config. ⁶ Peak = weekdays 5-11 AM PT; shows countdown to next transition. ⁷ Uses tagPatterns config (default ["v*"]); auto-hides when no pattern matches a reachable tag. ⁸ Auto-hides if ~/.gemini/antigravity-cli/antigravity-oauth-token not found.

i18n: English and Korean supported (auto-detect or set via setup).

Configuration

# Preset modes
/claude-dashboard:setup compact             # 1 line (default)
/claude-dashboard:setup normal en pro       # 2 lines, English, Pro plan
/claude-dashboard:setup detailed ko max     # 6 lines, Korean, Max plan

# Custom mode: control widget order and line composition
# Format: "widget1,widget2,...|widget3,widget4,..." (| separates lines)
/claude-dashboard:setup custom auto max "model,context,cost|projectInfo,todoProgress"

Plan differences:

Feature	Max	Pro
5h rate limit + countdown	✅	✅
7d all models	✅	❌

Advanced Configuration

Interactive Mode: Run /claude-dashboard:setup without arguments. Best for preset selection; for full widget control, use Direct Mode or edit the JSON file directly.

Display Mode Presets (zaiUsage and rateLimit* are mutually exclusive based on provider):

Mode	Lines	Widgets
`compact`	1	model, context, cost, rateLimit5h/7d/7dSonnet, zaiUsage
`normal`	2	+ projectInfo, sessionId, sessionDuration, burnRate, todoProgress
`detailed`	6	+ depletionTime, configCounts, toolActivity, agentStatus, cacheHit, promptCache, performance, tokenBreakdown, forecast, budget, codexUsage, geminiUsage, antigravityUsage, linesChanged, outputStyle, version, peakHours, lastPrompt, vimMode, apiDuration, tagStatus

Configuration file (~/.claude/claude-dashboard.local.json):

{
  "language": "auto",
  "plan": "max",
  "displayMode": "custom",
  "lines": [
    ["model", "context", "cost", "rateLimit5h"],
    ["projectInfo", "todoProgress"]
  ],
  "theme": "default",
  "separator": "pipe",
  "dailyBudget": 15,
  "disabledWidgets": [],
  "modPane": "detailed",
  "modBand": "MC$R|BDO",
  "modBandDefault": false,
  "cache": { "ttlSeconds": 60 }
}

Or use preset shorthand for quick configuration:

{
  "preset": "MC$R|BDO",
  "theme": "tokyoNight",
  "separator": "dot"
}

Themes: default (pastel) / minimal (monochrome) / catppuccin / catppuccinLatte (light-mode) / dracula / gruvbox / nord / tokyoNight / solarized

Separators: pipe (│, default) / space / dot (·) / arrow (›)

Preset Shortcuts: Quick layout with single characters — "preset": "MC$R|BDO" (M=model, C=context, $=cost, R=rateLimit5h, etc.)

Budget Tracking: Set "dailyBudget": 15 to track daily spending. Shows ⚠️ at 80% and 🚨 at 95%.

Tag Status: Customize tagStatus patterns via "tagPatterns": ["v*", "release-*"]. Default is ["v*"]. The widget auto-hides when no pattern matches a reachable tag.

Widget Toggle: Add widget IDs to disabledWidgets to hide them from any display mode.

Mod Layouts: modPane (the /claude-dashboard-pane pane, default detailed) and modBand (the /claude-dashboard-band band, default = your status line layout) take a display mode name (compact / normal / detailed), a preset string like "MC$R|BDO", or custom widget lines like [["model","context"],["sessionIdFull"]] (same as the status line's lines). Set "modBandDefault": true to turn the band on at session start. See Mods.

Color Legend: 🟢 0-50% Safe / 🟡 51-80% Warning / 🔴 81-100% Critical

Commands

`/claude-dashboard:setup`

Configure the status line display mode, language, and plan. See Configuration.

`/claude-dashboard:check-usage`

Check usage limits for all AI CLIs (Claude, Codex, Gemini, Antigravity, z.ai) at once and get a recommendation for which CLI has the most available capacity.

/claude-dashboard:check-usage              # Interactive output with colors
/claude-dashboard:check-usage --json       # JSON output for scripting
/claude-dashboard:check-usage --lang ko    # Specify language

check-usage

`/claude-dashboard:setup-alias`

Add a check-ai shell alias to quickly check all AI CLI usage from your terminal. Supports macOS/Linux (zsh/bash) and Windows (PowerShell).

/claude-dashboard:setup-alias

After setup:

check-ai          # Pretty output
check-ai --json   # JSON output for scripting

`/claude-dashboard:update`

Repair or verify the statusLine shim. Usually unnecessary — after /plugin update, the status line picks up the new version on its own. Use this if you have hooks disabled or the status line stops updating.

/claude-dashboard:update

Mods (pane & band)

claude-dashboard also ships as a Claude Code mod (function-hook plugin, early access, tested on Claude Code 2.1.289). It is bundled in the same plugin (hooks/hooks.json → "modules": ["../dist/mod.js"]), so there is nothing extra to install. Mods are drawn only in the terminal and the desktop Code tab (not the VS Code panel, not claude -p).

Command	What it does
`/claude-dashboard-pane [on\|off]`	Open or close a dashboard pane beside the transcript (no argument flips it). Layout from `modPane` (default `detailed`).
`/claude-dashboard-band [on\|off]`	Draw the dashboard above the prompt and hide the status line for this session only (`settings.json` is untouched). Layout from `modBand` (default = your status line layout).

{
  "modPane": "detailed",
  "modBand": "MC$R|BDO",
  "modBandDefault": true
}

modPane / modBand accept a display mode name (compact / normal / detailed), a preset string, or custom widget lines ([["model","context"],["sessionIdFull"]]). Unknown widget ids are dropped; if nothing is left, the default is used. modBandDefault: true turns the band on at session start.
Interactive /claude-dashboard:setup asks how you want to use the mod dashboard (status line only, peek with pane, replace with band, or both) and writes these keys; rerunning setup keeps keys it does not ask about.
How hiding works: the band writes a per-session heartbeat marker (~/.cache/claude-dashboard/band-<sessionId>), refreshed on every render (at most every 60s) and ignored after 180s. It is deleted on off and at session end, so if the mod stops the status line comes back by itself within 3 minutes.
Theme, language, and disabledWidgets follow your normal config. cacheHit, tokenBreakdown, and performance are hidden in the pane and band (the mod API has no per-request cache usage).
Data comes from the mod API (context, rate limits, and cost pushed by Claude Code) and the unchanged renderer dist/index.js, run as a subprocess.

Troubleshooting

Status line not showing

Check if plugin is installed: /plugin list
Verify settings.json has a statusLine entry pointing at plugins/data/claude-dashboard-claude-dashboard/statusline.mjs
If it's still not showing, try restarting Claude Code

Rate limits showing ⚠️

API token may be expired - re-login to Claude Code
Network issue - check internet connection
API rate limited - wait for the cache to refresh (cache.ttlSeconds, default 300 seconds)

Multiple accounts (CLAUDE_CONFIG_DIR)

Claude Code relocates its whole config directory — credentials, settings, and history — when CLAUDE_CONFIG_DIR is set. That is how two accounts run side by side:

# Personal Max account, kept separate from the default ~/.claude
CLAUDE_CONFIG_DIR=~/.claude-max claude

The status line follows the same variable, so each session reports the account that is actually rendering it. Leave it unset and the default ~/.claude is used, as before.

Notes:

The variable must be a single directory path, and must be exported to the session.
On macOS the OAuth token comes from the Keychain, which holds one entry for all accounts — CLAUDE_CONFIG_DIR separates settings.json and history.jsonl reads, but rate-limit API calls use whichever OAuth token the Keychain holds.
/claude-dashboard:setup and /claude-dashboard:update register the status line into the session's config dir ($CLAUDE_CONFIG_DIR if set, ~/.claude otherwise) — run them once per account. The dashboard's own display config ~/.claude/claude-dashboard.local.json is intentionally shared across accounts.

Wrong language

Run setup with explicit language:

/claude-dashboard:setup normal ko  # Korean
/claude-dashboard:setup normal en  # English

Cache issues

API response cache is stored in ~/.cache/claude-dashboard/. To clear:

rm -rf ~/.cache/claude-dashboard/

Cache files are automatically cleaned up after 1 hour.

Development

npm install && npm run build

See CONTRIBUTING.md for details.

Star History

☕ Support

If you find this plugin useful, support development:

License

MIT

Significant stargazers

Agentic-Worker

19 followers · starred Jan 2026

Similar repos

jarrodwatts/claude-hud

A Claude Code plugin that shows what's happening - context usage, active tools, running agents, and…

28,332

lenadweb/stream-deck-ai-limits

Stream Deck plugin to monitor AI coding usage limits and reset times for Claude, Codex,…

steipete/CodexBar

Show usage stats for OpenAI Codex and Claude Code, without having to login.

22,220

dsebastien/claude-epic-status-line

A feature-rich status line for Claude Code with colors, rate limits, git info, session cost,…

mryll/claudebar

Claude Code usage limits for Waybar and the Omarchy shell. Session, weekly, per-model, and…

Javis603/token-monitor

Local-first desktop widget for tracking token usage, costs, and limits across 43+ AI coding…

2,637

technical-turtle/cc-context-telemetry

Show Claude Code's context % and your 5h/7d usage-limit consumption next to your existing…

anantraghunath/claude-code-usage-quota-mod

Know your Claude limits before they hit you (Live band above the Claude Code prompt): 5 Hour and…