OpenCode HUD

OpenCode TUI HUD plugin with visual context, token usage, cache, spend, model-flow dashboards, and AI-configurable settings.

Install

Local development install:

npm install -g "C:\\path\\to\\opencode-hud"

From npm:

npm install -g @stalfh/opencode-hud
opencode-hud install

npm install only installs the package and prints the next step. opencode-hud install explicitly enables both the TUI HUD and the server-side configuration tools, preserving existing settings and creating backups before changes.

Enable In OpenCode

The CLI configures these files automatically:

~/.config/opencode/tui.json       # TUI HUD display
~/.config/opencode/opencode.json  # server tools for AI configuration

To configure manually, add the plugin to both files.

~/.config/opencode/tui.json:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    "@stalfh/[email protected]"
  ]
}

~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "@stalfh/[email protected]"
  ]
}

For local file testing, use:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    "file:///C:/path/to/opencode-hud/src/tui.tsx"
  ]
}

Restart OpenCode after changing plugins or configuration.

Useful CLI commands:

opencode-hud status
opencode-hud install
opencode-hud uninstall
opencode-hud config describe
opencode-hud config set sidebar.width 38
opencode-hud config template compact
opencode-hud config note "Today focus"
opencode-hud config validate

AI Configuration

After running opencode-hud install and restarting OpenCode, the package exposes server tools that OpenCode can use to configure HUD settings safely.

Example prompts inside OpenCode:

HUD 改成 compact，note 写“今天专注”，隐藏 git。

HUD 侧边栏宽度改成 38，只保留 note、identity、contextGauge。

The tools validate manifest-backed config paths and write user overrides to:

~/.config/opencode/opencode-hud.config.json

The assistant should use HUD tools instead of editing JSON manually. Changes may require restarting OpenCode because plugin configuration is loaded at startup.

User Configuration

The plugin reads user configuration from:

~/.config/opencode/opencode-hud.config.json

On Windows, copy the example config with:

Copy-Item "$env:APPDATA\npm\node_modules\@stalfh\opencode-hud\config\opencode-hud.config.example.json" "$env:USERPROFILE\.config\opencode\opencode-hud.config.json"

Sidebar Templates

Set sidebar.style to one of:

"cards"
"compact"
"plain"
"minimal"

• cards: full continuous dashboard panel.
• compact: dense multi-line summary.
• plain: readable text list.
• minimal: four-line critical status.

Sections

Reorder or remove sidebar sections using sidebar.sections:

"sections": [
  "note",
  "identity",
  "session",
  "contextGauge",
  "contextTrend",
  "tokenBreakdown",
  "cacheGauge",
  "spend",
  "modelFlow",
  "globalUsage",
  "modelUsage",
  "git"
]

Removing a section hides it.

Visual Options

Customize visual modules with visuals:

"visuals": {
  "barWidth": 10,
  "contextTrendPoints": 12,
  "modelFlowMax": 6,
  "modelFlowNameWidth": 9,
  "modelFlowSeparator": " → ",
  "showContextHeadroom": true,
  "showReasoningInTokenMix": true,
  "cacheRatings": {
    "excellent": 90,
    "good": 70,
    "mixed": 40
  },
  "labels": {
    "contextGauge": "Context Gauge",
    "contextTrend": "Context Trend",
    "tokenBreakdown": "Token Mix",
    "cacheGauge": "Cache",
    "spend": "Spend",
    "modelFlow": "Model Flow"
  }
}

Paths

The plugin resolves paths from the current user home directory:

~/.config/opencode/opencode-hud.config.json
~/.config/opencode/opencode.json
~/.local/share/opencode/opencode.db

For testing, override the home directory with:

$env:OPENCODE_HUD_HOME = "C:\\Users\\YourName"

Test

bun test