Subagent Monitor

See delegated work without leaving OpenCode. Subagent Monitor is an MIT-licensed OpenCode TUI sidebar plugin that keeps running, completed, and failed subagents visible, with elapsed time and token/context usage when OpenCode provides it.

Install

Add the package to your OpenCode TUI configuration:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["opencode-subagent-statusline"]
}

The configuration usually lives at:

~/.config/opencode/tui.json

Restart OpenCode after saving the file. The package is published as opencode-subagent-statusline and requires Node >=22.13.

Why Subagent Monitor?

Delegating work is powerful, but child sessions can disappear into the background. Without a visible status surface, you have to guess:

• Is the review agent still running?
• Did the test agent finish?
• Which child session failed?
• How much context did a subagent use?

Subagent Monitor restores that visibility inside OpenCode, so you can keep working while still knowing what your delegated agents are doing.

What you get

The sidebar shows:

• running subagents;
• recent completed subagents;
• failed subagents;
• elapsed time;
• token/context usage when available.

When subagent activity is active, the plugin also adds a compact summary to the home/footer area.

Gentle AI integration

Gentle AI offers Subagent Monitor as an optional OpenCode community plugin. Select and install it through Gentle AI to add the selected plugin to OpenCode's tui.json, or install this package directly using the configuration above.

This integration is optional. Subagent Monitor remains an independently installable OpenCode plugin.

Screenshots

Full OpenCode context with demo content in Spanish:

Focused sidebar view:

Keyboard navigation

Run Subagents: Focus sidebar list from the OpenCode command palette, or press Alt+B, to focus the subagent sidebar list without using the mouse. List navigation shortcuts are handled only while the sidebar list is focused.

Opening a selected session is a no-op when there is no visible or navigable subagent.

Click Σ in the sidebar aggregate row to toggle completed history with the mouse. The toggle is not persisted; it resets when OpenCode or the plugin is reloaded. Completed history is bounded retained history, not a full database: terminal rows are kept for up to 3 days with a 1,500-row cap, and rows already pruned from state are not restored.

When a child session is opened from the sidebar, returning with OpenCode Up (session_parent) moves keyboard focus to the parent prompt so you can type immediately.

Documentation

For deeper installation, architecture, event-flow, state, rendering, TUI, configuration, testing, and troubleshooting details:

• English documentation
• Documentación en español
• Testing strategy

Troubleshooting

The plugin does not show up

Check OpenCode logs:

grep -n "subagent-statusline\|failed to load tui plugin" ~/.local/share/opencode/log/*.log

Then restart OpenCode after changing tui.json.

I installed a new version but OpenCode still behaves like the old one

OpenCode may be using a cached package. Try clearing the cached package directory under:

~/.cache/opencode/packages/

Then restart OpenCode.

Token/context usage is missing

OpenCode event payloads can vary by version and by event type. The plugin shows token/context usage when it is available and safely omits it when it is not.

Local privacy and persistence

The plugin persists a local JSON state file and status.txt snapshot under XDG_RUNTIME_DIR or the system temp directory by default. Those files can include OpenCode-derived subagent titles and summaries, which may contain short fragments derived from prompts or task descriptions. Files are written best-effort with owner-only permissions and atomic temp-file replacement where Node and the host filesystem support them.

OPENCODE_SUBAGENT_STATUSLINE_STATE overrides the state file path. Treat that environment variable as trusted local configuration because the plugin will write status data to the configured path.

For token/context backfill, the TUI reads recent local OpenCode SQLite/log data only from the user's OpenCode data directory. Very large log files are skipped to avoid blocking the TUI.

pnpm install --ignore-scripts

pnpm build

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["/absolute/path/to/sub-agent-statusline/dist/tui.js"]
}

opencode-subagent-statusline          -> TUI plugin
opencode-subagent-statusline/tui      -> TUI plugin
opencode-subagent-statusline/runtime  -> experimental/diagnostic runtime mode

pnpm build
pnpm typecheck
pnpm test
pnpm test:watch
pnpm test:coverage
pnpm pack --dry-run

Community and releases

• npm package
• GitHub repository
• Releases
• Issues
• Contributing
• Code of Conduct
• Security policy

License

MIT