OpenCode Voice

OpenCode Voice is a TUI plugin that reads assistant responses aloud with local Piper TTS.

The MVP supports manual readback, automatic readback, Codex-based speech summarization, stop/cancel controls, and FIFO queueing so background agent notifications do not overlap voices.

Requirements

• OpenCode with TUI plugin support.
• Piper executable, usually piper-tts.
• A Piper .onnx voice model.
• One local audio player: paplay, aplay, pw-play, play, or ffplay.
• Optional but recommended: Codex CLI for concise speech preparation.

Production installation

This package is intended to be published as @velnae/opencode-voice.

Build and inspect a local tarball:

npm run typecheck
npm pack

Install the tarball into a stable plugin directory that is separate from this source checkout:

mkdir -p ~/.local/share/opencode/plugins
npm install --prefix ~/.local/share/opencode/plugins ./velnae-opencode-voice-0.1.0.tgz

Then load the packaged dist entry from OpenCode TUI config:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    [
      "/home/you/.local/share/opencode/plugins/node_modules/@velnae/opencode-voice/dist/index.js",
      {
        "backend": "piper",
        "piperCommand": "piper-tts",
        "piperModelPath": "/path/to/voice.onnx",
        "playerCommand": "auto",
        "autoSpeak": false,
        "speechPreparationProvider": "codex",
        "codexCommand": "codex",
        "codexModel": "gpt-5.1-codex-mini",
        "codexTimeoutMs": 12000,
        "debug": false
      }
    ]
  ]
}

You can also install from GitHub when you want the current repository version:

npm install --prefix ~/.local/share/opencode/plugins github:velnae/opencode-voice

The package build runs during packing and GitHub installation so dist/index.js is available without loading src/index.ts from the source checkout.

Restart OpenCode after changing TUI plugin config or installing/updating the plugin package. OpenCode loads plugins at startup.

TUI plugin configuration

Load this plugin from OpenCode TUI config, not from project opencode.json server plugin config.

Production ~/.config/opencode/tui.json should point at the packaged dist entry installed above:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    [
      "/home/you/.local/share/opencode/plugins/node_modules/@velnae/opencode-voice/dist/index.js",
      {
        "backend": "piper",
        "piperCommand": "piper-tts",
        "piperModelPath": "/path/to/voice.onnx",
        "playerCommand": "auto",
        "autoSpeak": false,
        "speechPreparationProvider": "codex",
        "codexCommand": "codex",
        "codexModel": "gpt-5.1-codex-mini",
        "codexTimeoutMs": 12000,
        "debug": false
      }
    ]
  ]
}

For local development only, you may load the TypeScript source directly from a checkout:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    [
      "/path/to/opencode-voice/src/index.ts",
      {
        "backend": "piper",
        "piperModelPath": "/path/to/voice.onnx"
      }
    ]
  ]
}

Restart OpenCode after changing TUI plugin config, installing a new package build, or editing plugin source code. OpenCode loads plugins at startup.

Key Piper options:

| Option | Default | Purpose | | --- | --- | --- | | piperCommand | piper-tts | Piper executable to spawn. | | piperModelPath | unset | Required local Piper .onnx model path. | | playerCommand | auto | Audio player command; auto selects the first supported local player. | | playerArgs | unset | Optional extra arguments passed to the player. |

Commands

| Command | Purpose | | --- | --- | | /tts-speak | Speak the latest assistant response now. | | /tts-stop | Stop current speech and clear queued readbacks. | | /tts-mode | Toggle automatic readback on or off. | | /voice-speak | Alias for /tts-speak. | | /voice-stop | Alias for /tts-stop. | | /voice-mode | Alias for /tts-mode. |

Speech preparation

By default, the plugin prepares assistant output before sending it to Piper. The goal is to speak what matters, not to read the screen literally.

With speechPreparationProvider: "codex", the plugin calls Codex CLI non-interactively using a safe read-only invocation. Codex is asked to produce a short spoken summary that skips command snippets, emoji, raw logs, code blocks, stack traces, and decorative status symbols.

If Codex is unavailable, times out, or returns unusable output, the plugin falls back to local markdown/noise cleanup.

Useful options:

| Option | Default | Purpose | | --- | --- | --- | | speechPreparationProvider | codex | codex, opencode, or fallback. | | codexCommand | codex | Codex CLI executable. | | codexModel | unset | Optional Codex model override. | | codexTimeoutMs | 12000 | Maximum time to wait for Codex speech prep. | | speechPreparation | true | Disable with false to skip LLM prep. | | debug | false | Show diagnostic TTS notifications when troubleshooting. |

Automatic readback and queueing

/tts-mode toggles automatic readback. The configured autoSpeak value is the startup default; the runtime toggle is persisted through OpenCode api.kv when available.

Automatic readbacks use a FIFO queue:

• each assistant response is captured when the event arrives;
• queued items are spoken one at a time;
• background agent notifications do not overlap voices;
• duplicate message IDs are skipped when OpenCode exposes stable IDs;
• /tts-speak is explicit user intent and takes priority;
• /tts-stop stops the current readback and clears the queue.

Piper playback

Piper is executed locally and offline. The plugin never scrapes terminal output; it reads assistant text through OpenCode APIs and sends prepared text to Piper.

For paplay, raw Piper audio is played with raw PCM arguments:

--raw --rate=22050 --format=s16le --channels=1

Runtime verification status

Validated in the OpenCode TUI runtime:

• /tts-speak speaks the latest assistant response.
• Codex speech preparation summarizes instead of reading raw output literally.
• /tts-stop cancels Codex preparation and Piper playback.
• /tts-mode toggles automatic readback.
• Two near-simultaneous background agent completion notifications were read sequentially through the FIFO queue, without overlapping Piper voices.

Static verification:

npm run typecheck
npm run build

Both commands pass for the MVP implementation.