OpenCode 2 plugin that displays a persistent status HUD below the text input in the TUI. It is a native TUI plugin, not an assistant-message renderer, so it does not add HUD content to a session transcript.
Add it to the plugins array in ~/.config/opencode/cli.json, for example:
{
"plugins": [
"@ndom91/opencode-hud"
]
}OpenCode downloads and loads the package. Restart OpenCode after changing the configuration.
Warning
To show 5h and weekly Codex subscription usage, the HUD plugin queries the OpenAI endpoint through
your system's Codex authorization. This is disabled by default. See PRIVACY.md before
enabling it with the codexUsage package option. This is the same mechanism as used by
CodexBar and others.
The default HUD can show the following native TUI data:
- Project path, branch, dirty state, and local change summary.
- Session context usage, including an amber
compaction likely soonwarning at 80% usage and the active compaction state. - Up to two running shell commands and the four most recent tool activities.
- The most recent failed tool for 15 seconds. A new user turn clears the failure row.
- Up to three running subagents, including elapsed time and their own context percentage.
- Optional Codex 5-hour and weekly usage limits.
The default HUD shows all available status rows. Disable individual groups with
package options in ~/.config/opencode/cli.json:
{
"plugins": [
{
"package": "@ndom91/opencode-hud",
"options": {
"agents": false,
"codexUsage": true,
"compaction": false,
"context": true,
"git": true,
"shell": true,
"tools": true
}
}
]
}| Option | Controls |
|---|---|
agents |
Running subagents, elapsed time, and context usage |
codexUsage |
Disabled by default. Set to true to show Codex 5-hour and weekly usage limits. |
compaction |
Active compaction state and the 80% context warning |
context |
Current session context usage |
git |
Branch, dirty state, and change summary |
shell |
Running shell commands |
tools |
Recent tool activity and brief tool-failure row |
Requirements:
opencode2- Node.js 24+
Install dependencies and validate the project:
pnpm install
pnpm format
pnpm typecheck
pnpm testStart OpenCode from this repository:
opencode2 .OpenCode discovers .opencode/plugins/tui/status.tsx automatically. Start or
open a session to see the HUD under the prompt.
Note
The OpenCode 2 plugin API is beta and liable to change. Please check NOTES.md and validate
against the installed @opencode-ai/plugin runtime types if making changes.
MIT