@superwhisper/opencode
Superwhisper voice integration plugin for OpenCode.
Get voice notifications when your AI coding tasks complete, and respond with your voice. Your voice response is sent back to OpenCode as the next prompt, creating a hands-free coding loop.
Requirements
Installation
curl -fsSL https://superwhisper.com/install-opencode.sh | bash
The script registers the plugin with every OpenCode CLI it finds:
| CLI | Command it runs |
|---|
| OpenCode 1.3.4+ | opencode plugin -g -f @superwhisper/opencode |
| OpenCode 1.0–1.3.3 | adds the plugin to plugin in ~/.config/opencode/opencode.json |
OpenCode 2 (opencode2, @opencode-ai/cli) | opencode2 plugin add @superwhisper/opencode |
Or add it to ~/.config/opencode/opencode.json yourself. OpenCode 1.x reads plugin, OpenCode 2 reads plugins:
{
"plugin": ["@superwhisper/opencode"],
"plugins": ["@superwhisper/opencode"]
}
How It Works
You speak → OpenCode works → Plugin notifies Superwhisper → You speak back → loop
- Task completes → OpenCode reports the turn finished
- Plugin extracts the response → fetches the last assistant message
- Plugin notifies Superwhisper → writes the message to a temp file and a payload to Superwhisper's inbox
- Superwhisper shows notification → displays summary with voice recording UI
- You speak your response → Superwhisper transcribes and writes to response file
- Plugin reads response → polls the response file, sends back to OpenCode
- OpenCode continues → processes your voice input as the next instruction
OpenCode 1 and 2
One package serves both plugin APIs:
@superwhisper/opencode (package root) default-exports the 1.x plugin function. OpenCode 1.0–1.2 calls every root export as a plugin, so the root exports nothing else.@superwhisper/opencode/server default-exports { id, server, setup }. OpenCode 1.3+ loads ./server and calls server; OpenCode 2 calls setup.
Both adapters map their events into the same engine (src/engine.ts), so Superwhisper sees the same payloads either way.
Events
| Superwhisper status | OpenCode 1.x | OpenCode 2 |
|---|
completed | session.idle | session.execution.succeeded |
error | session.error | session.execution.failed |
permission | permission.asked (1.0: permission.updated) | permission.asked |
question | question.asked | form.created (forms where every field has options) |
OpenCode 2 has no plugin API for answering forms, so the plugin answers them over the local service's HTTP API. It reads the URL and password from ~/.local/state/opencode/service.json, and only when that file's pid matches the plugin's own process. Forms with free-text, number or conditional fields stay in the OpenCode UI.
Controlling Superwhisper During a Session
You can ask the agent to enable or disable Superwhisper voice notifications at any time during a session. The plugin exposes a superwhisper_toggle tool that the agent will use automatically when instructed.
Disable Superwhisper for the current session:
"Disable Superwhisper" / "Turn off voice notifications" / "Stop Superwhisper"
Re-enable Superwhisper for the current session:
"Enable Superwhisper" / "Turn voice notifications back on" / "Re-enable Superwhisper"
The toggle is session-scoped — it only affects the current OpenCode session and resets when you start a new one.
Development
bun install
bun test
bun run typecheck
Local Testing
Build and install to your local OpenCode plugin folder:
bun run install-local
Or watch for changes and auto-install on save:
bun run dev
Both commands bundle the plugin and copy dist/server.js to ~/.config/opencode/plugin/superwhisper.js (OpenCode 1.3+). OpenCode picks it up on next session. For OpenCode 2, point plugins at a directory containing a server.js that re-exports dist/server.js.
Environment Variables
| Variable | Default | Description |
|---|
SUPERWHISPER_DEBUG | unset | Set to 1 to enable debug logging (outputs to OpenCode's log) |
Project Structure
src/
index.ts # Package root: OpenCode 1.x plugin function
server.ts # ./server: { id, server, setup } for OpenCode 1.3+ and 2
v1.ts # OpenCode 1.x adapter (hooks, event mapping, replies)
v2.ts # OpenCode 2 adapter (setup, event mapping, forms)
engine.ts # Version-independent notification/poll state machine
inbox.ts # Superwhisper file inbox delivery
system.ts # pgrep/open/git via child_process
types.ts # Engine events, Host interface, constants
message.ts # Message extraction and summary
poll.ts # Response file polling
normalize.ts # Question/permission response normalization
*.test.ts # Tests
License
MIT
