opencode-agent-progress

Live OpenCode sidebar progress for the main session, OMO agents, background jobs, and ULW loops.

The plugin exists to keep progress visible when host-level redraws lag behind state updates. It reads OpenCode session state directly, consumes the OMO v1 mirror, and updates mounted OpenTUI nodes without requiring the user to leave and re-enter a session.

Requirements

• OpenCode 1.18.3 (verified; other releases require the validation described below)
• @opencode-ai/plugin 1.17.x
• OpenTUI 0.3.4 through 0.4.x
• OMO 4.19.x for agents, jobs, and ULW mirror data

The main-session section works without OMO. When no compatible mirror exists, the sidebar reports waiting, invalid, or stale instead of rendering untrusted data.

Installation

Add the package to ~/.config/opencode/tui.json. Keep the OMO entry so it remains installed, but deactivate only its TUI module to avoid duplicate sidebar sections:

{
  "plugin": [
    "oh-my-openagent@latest",
    "opencode-agent-progress@latest"
  ],
  "plugin_enabled": {
    "oh-my-openagent:tui": false
  }
}

Do not set OMO's tui.sidebar.enabled to false. That setting also stops the server-side mirror writer, so agent, job, and ULW state would no longer reach this plugin.

Leave oh-my-openagent@latest enabled in opencode.json so OMO orchestration and mirror generation keep running. Restart the OpenCode TUI after changing plugin configuration, then open the sidebar with the configured sidebar_toggle binding. The default is <leader>b.

For local development, clone the repository, run pnpm install, and replace the npm entry with file:///absolute/path/to/opencode-agent-progress/src/tui.tsx.

Displayed state

• Main: session title, status, active agent, and model.
• Agents: active OMO agent names and states.
• Jobs: bounded job labels, status, and tool-call count.
• ULW: goals, checks, queue, and active goal.
• OMO: mirror health when live OMO state is unavailable.

Status is always expressed as text. Theme colors add emphasis but never carry meaning alone.

Runtime design

OpenCode events trigger immediate reads for connection, session, message, and todo updates. A one-second poll is retained for OMO's file mirror and as a reconnect fallback. Identical views are deduplicated.

The sidebar uses fixed OpenTUI row slots and updates TextRenderable nodes directly. Each changed node requests its own render; the plugin does not call the host's global api.renderer.requestRender(). Mounted nodes own controller cleanup, so event subscriptions and timers are released when the sidebar is destroyed or replaced.

OMO mirror compatibility is intentionally strict:

• SHA-1 project hash and canonical path matching follow OMO's mirror-path contract.
• Zod parses schema version 1 at the file boundary.
• Mirrors older than six seconds are marked stale.
• Unknown schemas fail closed as invalid.

Development

bun test
bun run typecheck
bun run lint
bun run build

bunfig.toml preloads the official OpenTUI Solid transform. Source TSX remains the package entry because OpenCode's TUI plugin loader compiles it in the host runtime.

Verified matrix

| Surface | Version | Result | |---|---:|---| | OpenCode | 1.18.3 | Local file plugin loaded from isolated tui.json | | @opencode-ai/plugin | 1.17.16 | Typecheck and runtime slot registration passed | | OpenTUI | 0.4.3 | In-memory renderer and real TUI passed | | OMO mirror | schema 1 | Missing-to-live refresh passed without session re-entry |

The isolated real-TUI check used a 120-column terminal. The plugin region measured 37 of 40 available columns, with no overflow and aligned borders.

Compatibility policy

Host and OpenTUI upgrades must pass pnpm check plus an isolated real-TUI run before the supported range is widened. A new OMO mirror schema requires a new parser branch and fixtures; it must not be accepted by loosening the current schema.