opencode-herdr

An OpenCode plugin integrating Herdr's terminal workspace controls with OpenCode. SQLite-backed agent coordination, coloured inbox/outbox views and Herdr shortcut hints. The core coordination lifecycle is implemented. See Setup and Limitations for supported operations and outstanding features.

Current behaviour

• Shows common pane, workspace, tab, navigation, and Herdr controls.
• Includes custom [[keys.command]] entries, using their descriptions where available.
• Reads configured bindings and the prefix from Herdr's config.toml. Empty bindings hide the corresponding action.
• Uses Herdr 0.9.1 defaults for omitted bindings or a missing config file. An invalid or unreadable file displays a warning instead.
• Only appears when OpenCode runs inside Herdr (HERDR_ENV=1).
• Uses OpenCode's theme and existing session sidebar. All sections start collapsed. Click headings to expand or collapse them.
• Displays keyboard hints only. Herdr handles the keys. Clicking a shortcut does not execute it.
• Separate tasks with handback and instructions with acceptance-only receipts.
• Durable FIFO delivery, immutable generation results, pause/resume, correlated questions, cancellation, notification outbox and redacted audit events.
• Local pane/workspace/worktree provisioning without automatic permission approval.
• Explicitly configured SSH peers, pinned machine identities and idempotent remote delivery.
• Coloured Coordination inbox/outbox in OpenCode and display-only queue tokens in Herdr.

npm Installation

Package: @quintindk/opencode-herdr. The first release is prepared as 0.1.0. Once that version is published, add it to both OpenCode configurations, preserving existing plugin entries.

~/.config/opencode/opencode.json enables the coordination server:

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

~/.config/opencode/tui.json enables the sidebar:

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

OpenCode installs the package and selects its ./server or ./tui export for each configuration. Use the package name in both files, without adding /tui to the npm specifier. Keep Herdr's OpenCode session-reporting integration installed, then quit and restart OpenCode inside Herdr. See Setup and Limitations.

Local Installation

Developed against OpenCode 1.18.27 and Herdr 0.9.1. Server and TUI entries are separate. Requires Node.js 22 or later to build. Read Setup and Limitations before enabling the server entry.

npm ci
npm run build

Register the sidebar in the plugin array in ~/.config/opencode/tui.json so it is available across projects. Preserve existing entries. The project-local tui.json only declares the schema:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["file:///absolute/path/to/opencode-herdr/dist/tui.jsx"]
}

Quit and restart OpenCode after installation, rebuilding, or changing Herdr bindings. Open a session with its sidebar visible. The section is not shown on the home screen. Keep Herdr's existing OpenCode session-reporting integration installed. This plugin does not replace it.

Enable coordination by adding the server entry to the plugin array in ~/.config/opencode/opencode.json, preserving existing entries:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["file:///absolute/path/to/opencode-herdr/dist/index.js"]
}

The repository does not register either entry automatically. Restart OpenCode after changing plugin configuration. Use /herdr to start coordinating and see the Tool Reference for arguments and examples.

The structured logging module is implemented and tested, but full worker/tool instrumentation is still outstanding. See Structured Logging for the module API and current coverage.

See Remote Delivery for explicit peer configuration and Herdr Sidebar for colour rules. All coordination headings start collapsed. Blue indicates queued/submitted, the theme accent indicates accepted, yellow indicates paused/unknown/review needed, green indicates completion and red failure.

Config resolution is HERDR_CONFIG_PATH, then $XDG_CONFIG_HOME/herdr/config.toml, then ~/.config/herdr/config.toml. Override the path through the TUI plugin options:

{
  "plugin": [
    ["file:///absolute/path/to/opencode-herdr/dist/tui.jsx", { "configPath": "/absolute/path/to/config.toml" }]
  ]
}

The file is read once on plugin load. This is not a query of the running Herdr client's effective keymap. Reload Herdr's configuration after editing it. When attaching remotely with client-local bindings, the server-side file may differ. Point configPath at an accessible copy of the client's config. Legacy key aliases/indexed configuration and duplicate-binding conflict resolution are not interpreted. Use Herdr's All shortcuts help for the complete active keymap.

Development

npm test
npm run typecheck
# Requires the installed OpenCode CLI, not a standalone Bun executable:
npm run test:sqlite-host
npm run test:server-host
# Requires Bun:
npm run test:coordination
# Requires Bun for the actual OpenTUI renderer:
npm run test:tui
# Requires Bun for the standalone logging module:
bun test test/log.test.ts
# Requires npm, Bun and the installed OpenCode CLI:
npm run test:package

The build compiles TUI JSX ahead of installation. Solid and OpenTUI are shared with the host and declared as optional peers, not bundled into the plugin. The package includes built modules, documentation, examples and the MIT licence. npm pack builds automatically. See npm Packaging and Release for package verification and publication commands.

Run npm audit for current dependency advisories. Check OpenCode TUI API compatibility before changing the pinned OpenTUI toolchain.

The coordination store uses bun:sqlite. See SQLite Driver Validation for host compatibility and multi-process/crash-recovery evidence. State is stored at ~/.config/opencode/opencode-herdr/coordination.sqlite, or under XDG_CONFIG_HOME when explicitly set. Do not sync the database with dotfiles.

Documentation

• Setup and Limitations
• Tool Reference
• Herdr Sidebar
• Remote Delivery
• SQLite Driver Validation
• Structured Logging
• npm Packaging and Release
• Coordination Data Model and Coordination Flows, including proposed features

References

• OpenCode TUI schema: https://opencode.ai/tui.json
• Sidebar API: @opencode-ai/[email protected], TuiPluginModule and sidebar_content in dist/tui.d.ts.
• Herdr bindings: herdr --default-config from Herdr 0.9.1.

Licence

MIT, copyright 2026 Quintin De Kok.