opencode-hypa

Hardwire Hypa into OpenCode — no MCP required.

OpenCode plugin that intercepts bash / shell tool calls and rewrites them through hypa rewrite --json before execution. Noisy command output is compressed locally and deterministically — the same hardwire pattern Hypa uses for Claude, Codex, and Pi.

OpenCode bash tool call
        ↓
  opencode-hypa plugin
        ↓
   hypa rewrite --json
        ↓
hypa git … / hypa -c "…"
        ↓
errors · warnings · failing tests · exit codes

Install

opencode plugin opencode-hypa --global

Or add to ~/.config/opencode/opencode.json / opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-hypa"]
}

Requirements

• OpenCode with plugin support
• Node.js 18+ (or Bun) for the plugin runtime
• Hypa available via PATH, or installed as this package’s dependency (@hypabolic/hypa)

What it does

Hypa outcome	Plugin behavior
Rewritten / GenericWrapper	Replaces the bash command with Hypa’s rewritten form
Passthrough	Leaves the original command alone
Deny	Blocks the tool call
Ask	Blocks by default; set OPENCODE_HYPA_ASK_NON_INTERACTIVE=allow to proceed
Rewrite error / timeout	Fails open — runs the original command

Commands that already start with hypa are never double-wrapped.

Agent visibility

When Hypa rewrites a command, OpenCode would otherwise hand the LLM a tool result whose title shows the rewritten command (hypa git log …) with no marker that a plugin changed it. The LLM can misread the prefix as its own typo. To prevent that, this plugin also registers tool.execute.after and annotates the tool result with a one-line note:

[hypa Rewritten] git log --oneline -10 => hypa git log --oneline -10

The note is prepended to both output.title and output.output, and the full record is written to output.metadata.hypaRewrite. Non-rewritten outcomes (passthrough / skipped / error) leave the tool result untouched.

Configuration

Set options in opencode.json as the second element of a nested plugin tuple (string | [name, options] — one array item, not a string plus a sibling object), or override any field with an environment variable (env wins over options).

{
  "plugin": [
    [
      "opencode-hypa",
      {
        "binary": "hypa",
        "rewriteTimeoutMs": 5000,
        "askNonInteractive": "deny",
        "enabled": true
      }
    ]
  ]
}

Option (PluginOptions)	Env var	Default	Description
binary	OPENCODE_HYPA_BIN	hypa (PATH / bundled)	Hypa executable or absolute path
rewriteTimeoutMs	OPENCODE_HYPA_REWRITE_TIMEOUT_MS	5000	Timeout for hypa rewrite --json
askNonInteractive	OPENCODE_HYPA_ASK_NON_INTERACTIVE	deny	allow or deny when Hypa returns Ask
enabled	OPENCODE_HYPA_ENABLED	true	Set false / 0 to disable the plugin

Diagnostics

In the OpenCode TUI, run /hypa to open a modal with:

• whether the plugin is enabled
• resolved Hypa binary path and whether it exists
• installed Hypa version (hypa --version, cached at TUI load)
• effective config for each field with source tag (env, options, or default)
• the last rewrite (input, command, outcome, timestamp) or none

Re-open /hypa to refresh the snapshot after config or rewrite changes.

Why not MCP?

hypa serve works as an MCP server, but the model has to choose those tools. This plugin rewrites every bash call automatically — the integration that actually saves context.

Development

npm install
npm test
npm run build

CI keeps a fast lockfile job on Node 18 and 22. A separate opencode-latest job (push/PR and weekly) installs @opencode-ai/plugin@latest from npm — the same version OpenCode publishes for the CLI (opencode-ai / GitHub Releases) — and re-runs typecheck, tests, the rewrite/hook smoke, and a real OpenCode bash-dispatch smoke (POST /session/:id/shell, with a dummy-model fallback because /shell does not invoke tool.execute.before). That canary sets SMOKE_REQUIRE_REAL_SHELL=1, so it fails when OpenCode stops sending real bash calls through the plugin hooks.

Publishing

Releases publish to npm via Trusted Publishers (GitHub OIDC). No long-lived npm token is stored in the repo.

1. On npm: opencode-hypa → Settings → Trusted Publisher
2. Add GitHub with:

Field	Value
Organization or user	kipyin
Repository	opencode-hypa
Workflow filename	publish.yml
Environment	(leave empty)

3. Publish a GitHub Release (vX.Y.Z), or run the publish workflow manually.

Related

• Hypa — local context runtime
• @hypabolic/pi-hypa — official Hypa extension for Pi
• OpenCode plugins

License

MIT