cstat

cstat

A Claude Code plugin that renders a multi-line status line with live usage metrics for Claude Max/Pro subscriptions.

▸ ENV: Opus 4.7 | CC: 2.1.116 | SK: 12 | HK: 3 | MCP: 2 | AG: 0 | Py: 3.14
● CONTEXT: ▓▓▓▓▓░░░░░░░░░░░░░░░░░░░░░░░░░ 18% | 176.0k/1.0M | EFFORT: ● high
▬ USE: 5H: 5% ↓4:05 | 7D: 15% ↓Sat 19:00 | T: 42/avg:502
◆ PWD: ACCEPT EDITS | dev/cstat | 1M | Commit: 25m ago

• ENV — model name, Claude Code version, skill / hook / MCP / agent counts, Python version
• CONTEXT — context-window usage bar, token counts, current effort level
• USE — server-reported 5h / 7d rate-limit percentages with reset countdowns, plus today's message count vs. your average
• PWD — permission-mode chip (when not default), repo-relative cwd, git status summary, age of last commit

Requirements

• Claude Code ≥ 2.1.80 — the USE line uses rate_limits from stdin, which was added in 2.1.80. Older versions render the USE line with zeros and em-dashes.
• python3 on your PATH — stdlib only, no pip install.

Install

/plugin marketplace add https://github.com/bit-incarnas/cstat
/plugin install cstat@status-bar
/cstat:setup

/cstat:setup writes the statusLine entry into ~/.claude/settings.json. Restart Claude Code and the bar appears.

Slash commands

Command	What it does
/cstat:setup	Wire statusLine into ~/.claude/settings.json (auto-detects your python3 path)
/cstat:stats	Detailed usage report — lifetime totals, per-model tokens, recent sessions, hourly histogram
/cstat:configure [section] [on|off]	Toggle the four sections, change plan tier, or override rate-limit targets

Configuration

Edit plugins/cstat/config/defaults.json directly or via /cstat:configure:

{
  "display": {
    "showEnv": true,
    "showContext": true,
    "showUsage": true,
    "showPwd": true
  },
  "plan": "Max",
  "limits": {
    "5h_messages": 250,
    "weekly_messages": 4500
  }
}

• display.* — toggle each of the four lines
• plan — "Max" or "Pro" (affects default rate-limit labels)
• limits.* — override limit targets (the USE line always uses server-reported percentages when available, so these only matter for legacy fallback)

Troubleshooting

Only the first line of the status bar is visible. Your terminal window isn't tall enough. Claude Code renders each newline as a separate row; a short window clips the lower rows.

USE line shows 0% and em-dashes. Claude Code < 2.1.80, or the rate_limits object isn't in stdin yet (very new session). Run claude --version.

Slash commands don't autocomplete. The plugin isn't loaded. Run /plugin and verify cstat@status-bar is enabled, or re-install with the install block above.

Notes

• Zero dependencies. The entire renderer is one Python file that reads JSON from stdin, hits a few files under ~/.claude/, and writes ANSI to stdout.
• File-based cache at /tmp/cstat_cache/ with per-key TTLs — delete the directory to force a cold render.
• Repo layout: the repo itself is a single-plugin marketplace. The plugin lives under plugins/cstat/.

License

MIT — see LICENSE.