tmux-claude-usage

Your Claude usage — progress bar, percent, and reset time — right in the tmux status bar. It uses the official usage data Claude Code already receives — no API calls, no tokens, no rate limits — and updates live as you work.

Contents

• How it works
• Requirements
• Installation
• Configuration
• Update frequency
• Contribution
• License

How it works

Two small pieces:

1. Harvester — a Claude Code status line command. Claude hands it official session data (including rate_limits) on every render; it writes your usage to a cache file and prints nothing, so no line appears inside the pane.
2. Segment — a tiny script your tmux status line calls. It reads that cache and renders the bar. Pure bash, no network.

Because the data comes from Claude itself, it's free and accurate, and refreshes whenever Claude renders — continuously while you work.

Requirements

• tmux 3.0+
• jq
• Claude Code, signed in with a Claude Pro or Max subscription. The usage data (rate_limits) is sent only to Pro/Max sessions.

Installation

1. Add the plugin via TPM:

set -g @plugin 'docker-run/tmux-claude-usage'

2. Place the segment in your status line:

set -g status-right '#{claude_usage}  %Y-%m-%d %H:%M'

3. Fetch and wire it up — press prefix + I (TPM clones the plugin), then run the installer once (from inside tmux, so it can locate the clone):

bash "$(tmux show-environment -g TMUX_PLUGIN_MANAGER_PATH | cut -d= -f2-)tmux-claude-usage/scripts/init.sh"

init.sh adds the status line command to Claude Code's settings.json (under ~/.claude, or $CLAUDE_CONFIG_DIR if you've set one), backing it up first. Use Claude Code normally and the bar fills in.

Already have a Claude status line? init.sh keeps it: it chains your line and the harvester through the single slot, so both run and your line still shows. Use --force to install only the harvester instead, or --uninstall to restore your original line.

Ordering matters. Claude Code has only one status-line slot. If you set up another status-line tool (e.g. ccstatusline) after this — or re-run its configurator later — it overwrites the slot and the usage bar silently stops updating. Just re-run init.sh to re-chain (it picks the other tool back up), or run init.sh --check to diagnose.

Without TPM

Clone it anywhere and source the entry point from your tmux.conf:

git clone https://github.com/docker-run/tmux-claude-usage \
  ~/.tmux/plugins/tmux-claude-usage

run-shell ~/.tmux/plugins/tmux-claude-usage/claude-usage.tmux

Then place #{claude_usage} in your status line (step 2) and run that clone's scripts/init.sh (step 3).

Uninstall

bash "$(tmux show-environment -g TMUX_PLUGIN_MANAGER_PATH | cut -d= -f2-)tmux-claude-usage/scripts/init.sh" --uninstall

Restores any status line it chained, removes the harvester from Claude's settings.json, and deletes the usage cache. To remove the plugin entirely, also drop the @plugin line and #{claude_usage} from your tmux config and run TPM clean (prefix + alt + u).

Configuration

Out of the box the segment shows the 5-hour session window, inherits your theme's color normally, and turns amber then red as you approach your limit. Everything below is tunable — for example, override the colors to match your theme (hex values or tmux color names both work).

Match the demo

The powerline look in the demo above is a full Tokyo Night Storm status-bar theme, not part of the plugin — the plugin only contributes the #{claude_usage} segment. For that exact look, check out examples/tokyo-night-storm.conf.

Update frequency

The bar repaints every status-interval seconds (standard tmux setting, default 15). Lower it for a snappier bar — it just re-reads a local file, so it's free:

set -g status-interval 5

Repainting isn't the same as refreshing, though: the underlying numbers only update when Claude Code renders and hands the harvester fresh data. Usage you rack up elsewhere — the browser, another machine — won't appear until a local Claude Code session renders again, so a number can sit unchanged while the real figure climbs. There's no token-free way to fetch it on demand. To avoid mistaking a stale figure for a live one, set @claude_usage_stale_after and the bar appends e.g. (stale 2 hr) once the cache passes that age:

set -g @claude_usage_stale_after 1800  # mark stale after 30 min

Contribution

See the CONTRIBUTION.md file.

License

MIT