claude-dashboard

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:

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

Normal (2 lines):

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

Detailed (6 lines):

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 with emoji, effort level for Opus/Sonnet/Fable (MAX/X/H/M/L), fast mode for Opus (↯)
	`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
	`todoProgress`	Todo completion rate
Analytics	`burnRate`	Token consumption per minute
	`cacheHit`	Cache hit rate percentage
	`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)
	`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, 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": [],
  "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.

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

`/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

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 60 seconds for cache refresh

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

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.github		.github
commands		commands
dist		dist
hooks		hooks
images		images
locales		locales
scripts		scripts
website		website
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
demo.gif		demo.gif
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

claude-dashboard

Demo

Installation

From Plugin Marketplace

Manual Installation

Display Modes

Widgets

Configuration

Commands

`/claude-dashboard:setup`

`/claude-dashboard:check-usage`

`/claude-dashboard:setup-alias`

`/claude-dashboard:update`

Troubleshooting

Development

Star History

☕ Support

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

claude-dashboard

Demo

Installation

From Plugin Marketplace

Manual Installation

Display Modes

Widgets

Configuration

Commands

/claude-dashboard:setup

/claude-dashboard:check-usage

/claude-dashboard:setup-alias

/claude-dashboard:update

Troubleshooting

Development

Star History

☕ Support

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`/claude-dashboard:setup`

`/claude-dashboard:check-usage`

`/claude-dashboard:setup-alias`

`/claude-dashboard:update`