opencode-status-hud

Real-time usage HUD for OpenCode CLI

Every assistant response shows your live usage at a glance:

> Sisyphus | claude-opus-4-6 | 42% | 85K/200K | $12.30 | 5h: 10% (3h 55m) | 7d: 24% (Mon 14:00)

  Agent      Model            Ctx%   Tokens     Cost    5h window           7d window

Install

npm install -g opencode-status-hud
opencode-status-hud install

Then start OpenCode normally. The HUD is active automatically.

opencode

Features

• Live API utilization — Real percentage from Anthropic and OpenAI Codex dashboards (5h and 7d windows with reset countdown)
• Context tracking — Token usage and context window percentage per message
• Session cost — Running dollar cost for the current session
• Agent-aware — Shows active agent name with color-coded theming
• Multi-provider — Anthropic Claude and OpenAI Codex, auto-detected from existing credentials
• Zero config — No environment variables required; credentials resolved from your existing provider setup
• Dim display — Renders as a blockquote so it stays visually unobtrusive

HUD Format

| Segment | Example | Description | |---------|---------|-------------| | Agent | Sisyphus | Active agent name (color-coded) | | Model | claude-opus-4-6 | Current model identifier | | Context % | 42% | Context window utilization | | Tokens | 85K/200K | Used / limit | | Cost | $12.30 | Session cost | | 5h window | 5h: 10% (3h 55m) | Provider rate limit — real % if API available, ~approx otherwise | | 7d window | 7d: 24% (Mon 14:00) | Weekly rate limit with reset time |

When the provider API is unreachable, windows fall back to ~ approximate values calculated from local token history.

How It Works

The plugin hooks into OpenCode's plugin system:

1. event — Tracks message.updated events to collect token usage per assistant message
2. chat.params — Captures model metadata and agent identity
3. experimental.text.complete — Appends the HUD line as a blockquote to assistant output
4. tool.execute.before/after — Feeds the state machine for tool transition tracking

Provider API data (Anthropic usage headers, OpenAI Codex billing) is polled in the background and cached to disk for instant display on restart.

Configuration

Defaults work out of the box. Override with environment variables only if needed:

| Variable | Values | Default | |----------|--------|---------| | OPENCODE_STATUS_HUD_USAGE_DISPLAY | output, prompt, output+prompt | output | | OPENCODE_STATUS_HUD_VERBOSITY | low, normal, high | normal | | OPENCODE_STATUS_HUD_PROMPT_PROFILE | minimal, balanced, verbose | minimal | | OPENCODE_STATUS_HUD_USAGE_PROMPT_INTERVAL_MS | 0 (disable) or >=1000 | 10000 |

Uninstall

opencode-status-hud uninstall
npm uninstall -g opencode-status-hud

For LLM Agents

Give your coding agent this instruction:

Install and configure opencode-status-hud by following:
https://raw.githubusercontent.com/Two-Weeks-Team/opencode-status-hud/refs/heads/master/docs/guide/installation.md

Requirements

• Node.js >= 22
• OpenCode CLI

License

MIT