# Show HN: OpenCode2 HUD

> Source: <https://github.com/ndom91/opencode-hud>
> Published: 2026-08-30 16:42:03+00:00

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](/ndom91/opencode-hud/blob/main/PRIVACY.md) before
enabling it with the `codexUsage`

package option. This is the same mechanism as used by
[CodexBar](https://github.com/steipete/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 soon`

warning 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 test
```

Start 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](/ndom91/opencode-hud/blob/main/NOTES.md) and validate
against the installed `@opencode-ai/plugin`

runtime types if making changes.

MIT