Skip to main content

Using Codex CLI? Try the sibling project Codex Statebar — the same status bar, built for Codex.

Claude Status Bar

Your Claude Code usage, at a glance. 5h / 7d rate-limit bars, reset countdowns, model, context window, and prompt-cache freshness — inline in Claude Code's status line.

PyPI Downloads Python CI License: MIT GitHub stars

English · 简体中文 · Install · Documentation

Aurora — the default look

Claude Code tells you almost nothing about where you stand against your rate limits. cs puts the numbers that matter on one quiet line at the bottom of your terminal: how much you have left, and when it resets.

Line Segments
Usage 5h / 7d rate-limit bars, reset countdowns, end-of-window projections (→NN%), model & context window, prompt-cache countdown, optional session cost or relay balance
Project git worktree marker (name (🌳3) / worktree (🌳3)), project name, branch, session +/− lines, duration, version
  • Official numbers — the same 5h / 7d limits Claude Code enforces, not a local guess.
  • Prompt-cache countdown — ❄ 4m23s tells you when the next turn pays full price.
  • Fast — native cache reader plus a background daemon; well under 1% CPU at one refresh per second.
  • Opt-in extras — cost, relay balance, git ahead/behind, activity, IP checks, IELTS writing-coach progress.

Install

curl -fsSL https://raw.githubusercontent.com/leeguooooo/claude-code-usage-bar/main/install.sh | bash

A prebuilt binary for macOS Apple Silicon and Linux x86_64 — no Python needed. Other platforms fall back to pip.

Windows (PowerShell, no admin):

irm https://raw.githubusercontent.com/leeguooooo/claude-code-usage-bar/main/install.ps1 | iex

pip / uv:

pip install claude-statusbar     # or: uv tool install / pipx install
cs --setup                       # wires the statusLine hook + installs the skill

Restart Claude Code and the bar appears. cs upgrades itself every 6 hours; if you're stuck on an old version, run cs upgrade or re-run the one-liner (why). More paths in the install guide.

Customize

Three looks — aurora with block bars (default), aurora with a thin line, and classic:

aurora, block bars (default) aurora, thin line classic

cs theme picks one with a live preview:

cs theme — pick a look with a live preview

cs theme                         # pick one with a live preview (↑/↓, Enter)
cs config set bar_glyph thin     # thin ━ line instead of ■ blocks (default)
cs config set style classic      # the original battery-bar look
cs config set narrow_layout stack # stack quota bars in narrow panes
cs preview                       # all three looks, with your real numbers
cs config show                   # every key, and which ones you changed

Documentation

Guide What's inside
Install Binary, PyPI, skill-only, plugin, Codex bridge
What it shows Every segment, icon and color threshold
Looks The three looks, slash commands
Configuration All keys, env vars, JSON output
Fast mode (daemon) Daemon, auto-start, refresh and caching
No-quota mode Relay / Bedrock / Vertex layout and balance
Cache countdown How ❄ 4m23s is computed
Troubleshooting cs doctor, IP checks, upgrading

Want charts and weekly cost breakdowns instead of one line? Run ccusage or Claude Code Usage Monitor in a side pane — they coexist with cs.

ccx — keeps a Claude Code session and a Codex thread linked on macOS. With the bar installed, ccx's menu bar app warns you when Claude's 5-hour window passes 90% or its weekly quota is exhausted, and offers to continue the newest session in Codex in one click (no config; ccx reads rate_limits from ~/.cache/claude-statusbar/last_stdin.json while it's fresh).

Contributing

PRs welcome — see CONTRIBUTING.md (setup, tests, architecture, release flow) and SECURITY.md. Changes per version: CHANGELOG.md.

Acknowledgments

  • @marcwimmer — original show_cache_age widget (#9)
  • claude-monitor — token-usage analysis library used as the optional fast-path data source
Contributors
MIT © leeguooooo · Built for people who live in Claude Code.

Author

Built by 郭立 (Guo Li / leeguoo) — leeguoo.com · GitHub · X · more tools in the *-use family.

Metadata

Release files for claude-statusbar 3.52.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for claude-statusbar 3.52.3
File Size Uploaded Provenance Actions
claude_statusbar-3.52.3.tar.gz 360.2 kB With provenance Details for claude_statusbar-3.52.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for claude-statusbar 3.52.3
File Interpreter ABI Platform Actions
claude_statusbar-3.52.3-py3-none-any.whl Python 3 none any Details for claude_statusbar-3.52.3-py3-none-any.whl

Total release size: 579.8 kB

Release files / claude_statusbar-3.52.3.tar.gz

Download URL claude_statusbar-3.52.3.tar.gz
Size 360.2 kB
Tags Source
SHA-256 checksum
How to use checksums
c9aa3415e76898d31af5844c26eaa0f2ccc68618fec4d4ebccde676b73056e17
BLAKE2b-256 checksum
How to use checksums
7134bc095039e4d51d15550d67dc07be55ab3d98aa89ee7138b5f389e7a0635e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

Release files / claude_statusbar-3.52.3-py3-none-any.whl

Download URL claude_statusbar-3.52.3-py3-none-any.whl
Size 219.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3b0c2fe3ac533098c89168a5c3cd40e950ec4b0e862b3b1adc9b8567fd3f2b76
BLAKE2b-256 checksum
How to use checksums
fc9ca60219135e145a724132f17eee66db76c92e24bd9cb9e6b5fecb50c76984
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

Security for claude-statusbar 3.52.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for claude_statusbar-3.52.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.52.3 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page