Tmux Agent Usage

tmux-agent-usage

Display AI agent rate limit usage in your tmux status bar. Shows session and weekly utilization for Codex, Claude, z.ai, and Grok with color-coded percentages and a braille reset indicator.

Compact mode (`--compact`):

• Green < 50%, yellow 50–79%, red 80%+
• Compact mode shows each provider's available usage windows with reset indicators
• Cache-first with 55s TTL - tmux refreshes stay instant

Install

Shell (recommended)

curl -fsSL https://raw.githubusercontent.com/raine/tmux-agent-usage/main/scripts/install.sh | bash

Homebrew

brew install raine/agent-usage/agent-usage

Cargo

cargo install --git https://github.com/raine/tmux-agent-usage

tmux setup

With TPM

Add to `~/.tmux.conf`:

# Configure which providers to show (default: codex)
set -g @agent-usage-providers "codex claude zai grok"

set -g @plugin 'raine/tmux-agent-usage'

The plugin auto-installs the binary if not found in PATH.

Manual

set -g status-right-length 120
set -g status-right '#(agent-usage codex)#(agent-usage claude)#(agent-usage zai)#(agent-usage grok)#[fg=green]%d.%m. %H:%M'

Then reload: `tmux source ~/.tmux.conf`

Providers

Codex

Probes rate limits via JSON-RPC by spawning `codex app-server`, with a PTY fallback that sends `/status` and parses the output. Requires `codex` in PATH (or set `CODEX_BINARY` env var).

Claude

Reads OAuth credentials from macOS Keychain (falling back to `~/.claude/.credentials.json`) and queries the `api.anthropic.com/api/oauth/usage` endpoint. Requires being logged into Claude Code.

Per-model weekly limits are metered separately from the plan-wide weekly window, and are shown after it under the model's own name:

Claude 5h:3% ⣿ wk:62% ⡇ Fable:84% ⡇

These