agent-usage-tmux

agent-usage-tmux

Tmux status bar plugin for showing Claude and Codex usage as compact progress bars.

Install

Add the plugin with TPM:

Then reload tmux or install plugins with TPM.

What It Shows

- Remaining usage percentage
- Time until reset
- Separate bars for Claude and Codex

Current format:

Clicking a bar

Every bar is a mouse range, so tmux can tell which one was hit. Needs
set -g mouse on.

- Left click flips that bar between the 5-hour window and the weekly one.
  While the weekly window is up, a w sits in front of the percentage and the
  reset is written as days:

- Right click opens a context menu for that bar:

Clicks next to a bar keep doing whatever they did before: the bindings remember
the previous MouseDown1Status / MouseDown3Status command and fall back to
it, so the window list still works and other status-line plugins that bind the
same keys survive.

Which window a bar shows lives in @agent_usage_window_claude /
@agent_usage_window_codex (5h or weekly) and can be preset:

Custom @agent_usage_cmd_* commands are called exactly as written - the window
flag only goes to the built-in fetchers.

Configuration

By default, the plugin fetches usage from:

- scripts/fetch_claude_usage.py
- scripts/fetch_codex_usage.py

Optional tmux overrides:

Hide the leading icons:

That changes the display to:

Development

Useful local commands: