Install

There are two installers. The standalone binary needs nothing on your machine (no Python); the pip/uv path installs the Python package.

Claude Code: standalone binary (recommended, no Python required)

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

install.sh detects your OS + CPU arch, downloads the matching prebuilt cs binary from the latest GitHub Release, verifies its SHA-256, installs it to ~/.local/bin (no sudo; everything under $HOME), and runs cs --setup to wire the statusLine + slash commands. The binary is a single self-contained executable — no Python, no pip, no dependencies.

Prebuilt targets: macOS Apple Silicon (arm64), Linux x86_64. On any other platform (Intel Mac, Linux arm64, Windows) the script automatically falls back to the pip installer below.

Security-conscious? Download and read it first:

curl -fsSL https://raw.githubusercontent.com/leeguooooo/claude-code-usage-bar/main/install.sh -o /tmp/cs.sh
less /tmp/cs.sh    # audit it
bash /tmp/cs.sh

Update later by re-running the same one-liner. (The binary can't pip-upgrade itself; cs upgrade prints this command for you.) The desktop HUD (cs hud) is not in the binary — it needs PyObjC; install it via the pip extra below.

Claude Code: pip / uv (the Python package)

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

There's also a pip-based one-shot script, web-install.sh, that auto-detects uv / pipx / pip (and bootstraps uv if you have none), then runs cs --setup — it needs Python 3.9+:

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

Restart Claude Code to see the bar. cs --setup writes the following into ~/.claude/settings.json (existing files are backed up first, other keys are preserved):

{
  "statusLine": {
    "type": "command",
    "command": "cs render",
    "refreshInterval": 1
  }
}

Since v3.6.0 cs --setup defaults to daemon mode (cs render + refreshInterval: 1), which keeps CPU under 1% continuously while ticking the cache-age countdown every second. The daemon is auto-started by cs --setup and lazy-respawns on cs render if it ever dies, so you never see a frozen bar. Opt out with cs --setup --inline (writes plain cs, ~3% CPU at 1Hz) or set refreshInterval to a higher value — cs --setup preserves any explicit value you've already chosen. See Fast mode (daemon) for details.

Codex: AgentParty local status bridge

Codex support is intentionally local and narrow: cs can show the AgentParty context for the current workspace when AgentParty has written ~/.agentparty/state/<workspaceId>/statusline.json. See AgentParty bridge for the full picture.

#agentparty · ⬡ xdream-agent · ◉ serving · 3 unread
   ↳ ●@ bob  shipped the auth patch 2m

Disable it with cs config set show_party false.

Skill-only install (already have cs)

If you already have the cs binary installed (e.g. via pip install) and just want the conversational claude-statusbar skill so Claude Code routes natural-language requests like "switch theme to nord" or "余量颜色改成 #4ec85b" to the right cs command:

npx skills add leeguooooo/claude-code-usage-bar -g -y

This installs only the skill globally. It does not install cs itself — the skill's actions all call out to the cs CLI, so you still need one of the install paths above for the binary. Use this path when distributing into environments that already manage Python tooling separately, or when you want to update only the skill without touching cs.

cs --setup already installs the same skill alongside the slash commands, so most users don't need this path.

Install as a Claude Code plugin

The repo ships a .claude-plugin/plugin.json, distributed via the leeguooooo/plugins marketplace. Inside Claude Code:

/plugin marketplace add leeguooooo/plugins
/plugin install claude-statusbar@leeguooooo-plugins

You still need the cs CLI (pip install claude-statusbar or uv tool install claude-statusbar) — the plugin only carries the slash commands; the heavy lifting is the Python package.