opencode-subagent-statusline

opencode-subagent-statusline

Subagent Monitor for OpenCode.

See what your subagents are doing without losing track of them: running, done, failed, elapsed time, and token/context usage when OpenCode exposes it.

This package works as a TUI sidebar plugin for OpenCode.

Why?

When you delegate work to subagents, they can disappear into the background. That is powerful, but it also makes it easy to lose visibility:

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

opencode-subagent-statusline adds a compact Subagent Monitor inside OpenCode so you can keep that information visible while you work.

Screenshot

Focused sidebar view:

Install

Add the plugin to your OpenCode TUI config:

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

Your TUI config usually lives at:

~/.config/opencode/tui.json

Restart OpenCode after editing the file.

What you get

The TUI plugin adds a sidebar section that shows:

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

It also adds a small home/footer summary when there is active subagent activity.

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.

Shortcut	Action
Alt+B	Toggle focus between the subagent sidebar list and the prompt.
j / ArrowDown	Move selection to the next visible subagent.
k / ArrowUp	Move selection to the previous visible subagent.
Enter	Open the selected subagent session.
h / ArrowLeft	Collapse the subagent section.
l / ArrowRight	Expand the subagent section.
Esc	Leave list focus mode and return to the prompt.

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

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 a deeper explanation of how the plugin works, see the structured docs:

• English documentation
• Documentación en español

They cover installation, architecture, event flow, state/counters, rendering, TUI behavior, advanced configuration, development/testing, and troubleshooting.

Local development

Install dependencies with lifecycle scripts disabled by default:

pnpm install --ignore-scripts

Build the plugin:

pnpm build

Test the local TUI build by pointing OpenCode directly at dist/tui.js:

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

Development notes

This project ships the OpenCode TUI sidebar plugin from src/tui.tsx.

The TUI bundle is built with tsup and esbuild-plugin-solid in Solid universal mode for OpenTUI compatibility.

Package entrypoints:

opencode-subagent-statusline          -> TUI plugin
opencode-subagent-statusline/tui      -> TUI plugin

Useful commands:

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

Security hardening for maintainers

Recommended local npm/pnpm hygiene, following guidance from Gentle AI and Liran Tal:

• install project dependencies with lifecycle scripts disabled when possible, for example pnpm install --ignore-scripts;
• consider setting user-level ignore-scripts=true for npm/pnpm and temporarily opt in only when a trusted package needs scripts;
• enable dependency age/cooldown policies where supported, for example npm config set min-release-age 3 or equivalent Renovate/Dependabot cooldowns;
• block or review git, tarball, URL, and other exotic dependency specs, for example npm config set allow-git none where supported;
• optionally screen new packages with tools such as npq or Socket Firewall before adding them.

These are maintainer/developer controls, not runtime enforcement by this plugin.

Release maintainers should also keep npm trusted publishing/OIDC enabled for this package, require npm 2FA on maintainer accounts, restrict and revoke legacy npm tokens once OIDC publishing is active, and protect the release branch in GitHub.

Testing

Automated tests use Vitest with @vitest/coverage-v8:

pnpm test
pnpm test:watch
pnpm test:coverage
pnpm typecheck

For the testing strategy, file map, examples, and current TUI/e2e boundaries, see docs/testing.md.

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.

License

MIT