opencode-groq-dictate 0.0.0-stage → 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonardo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# opencode-groq-dictate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![opencode v2](https://img.shields.io/badge/opencode-v2-orange.svg)](#requirements)
+[![npm](https://img.shields.io/npm/v/opencode-groq-dictate?label=npm)](https://www.npmjs.com/package/opencode-groq-dictate)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![release](https://img.shields.io/github/v/tag/LeonVeganMan/opencode-groq-dictate?label=release)](https://github.com/LeonVeganMan/opencode-groq-dictate/releases)
+[![tests](https://img.shields.io/badge/tests-bun%20test-informational.svg)](#development)
+
+Dictation inside the **opencode v2** TUI: press `alt+v`, speak, press `alt+v` again.
+The take goes to Groq (`whisper-large-v3-turbo` by default) and the transcript is
+pasted into the prompt, ready to edit. `esc` throws a take away without uploading it.
+
+The sidebar carries the state, the model, the language, the spend and the request
+count, so you can see what the plugin is doing and what it costs while you dictate.
+
+## Why a plugin and not a global shortcut
+
+The usual setup is a shell script bound to a desktop shortcut: it records in one
+process, then pastes with `xdotool ctrl+v` into whatever window has focus. That works
+until the focus is somewhere else, and it leaves the transcript in no-man's land.
+
+Here recording, upload and paste all happen inside the TUI. The text is put on the
+clipboard and handed to `prompt.paste`, so it always lands in the composer, at the
+cursor, as if it had been pasted by hand.
+
+## Requirements
+
+- **opencode v2** — the generation whose TUI plugins are loaded from
+  `~/.config/opencode/plugins/` and built on `@opencode/plugin/tui` (`ui.slot`,
+  `ui.dialog`, `keymap.layer`). The v1 plugin API is a different generation and this
+  plugin does not target it.
+- `parec` (`pulseaudio-utils`) to record, `xclip` to place the transcript on the
+  clipboard. Both are already installed on a normal PulseAudio/PipeWire desktop.
+- A Groq API key, free tier is enough. It is asked once, on the first `alt+v`, and kept
+  in the opencode plugin storage — never in this repository.
+
+`bun` is only needed for the tests.
+
+## Install
+
+```bash
+git clone https://github.com/LeonVeganMan/opencode-groq-dictate.git \
+  ~/.config/opencode/plugins/opencode-groq-dictate
+```
+
+Local plugins are discovered from `~/.config/opencode/plugins/<name>/`: no entry in
+`opencode.json` is needed. Restart the TUI afterwards — plugins are read at startup and
+there is no hot reload.
+
+The clone above stays the documented install — opencode loads plugins from that folder —
+and the package is also on npm as
+[`opencode-groq-dictate`](https://www.npmjs.com/package/opencode-groq-dictate) for
+directories and registries that index plugins.
+
+## Usage
+
+| Key | Action |
+|-----|--------|
+| `alt+v` | start recording, press again to stop and transcribe |
+| `esc` | cancel the take: no upload, no request, no cost |
+| `/dictate` | same as `alt+v`, from the command palette |
+
+A take stops on its own after 60 seconds. Everything else is in the palette under
+**Voice**: `Dictation model`, `Dictation language`, `Dictation quota`.
+
+Super+V cannot be used: VTE (Tilix, xfce4-terminal) only enables xterm
+`modifyOtherKeys`, which never reports the Super modifier, so the binding could not
+fire inside the terminal. `alt+v` is reported by both the legacy and the
+`modifyOtherKeys` encodings.
+
+## Screenshots
+
+![Sidebar panel](assets/sidebar.png)
+
+The sidebar panel, without a border, same shape and colours as
+[opencode-go-meter](https://github.com/LeonVeganMan/opencode-go-meter). Nothing in it is
+decoration: every row is clickable and does something.
+
+| Row | Shows | Click |
+|-----|-------|-------|
+| `Groq Dictate` (title) | the panel name, muted | start / stop a take |
+| `state` | `idle`, `● rec 12s`, `transcribing…` | start / stop a take |
+| `model` | `large-v3-turbo` or `large-v3` | model dialog |
+| `lang` | `it`, `en`, `auto`, … | language dialog |
+| `today` | `$0.0032 · 13` takes | quota dialog |
+| `total` | `$0.0093` since the log began | quota dialog |
+| `last` | `7.3s · $0.0001` of the last take | — |
+| `rpm` | `1/20` requests in the last minute | quota dialog |
+
+The state row is green when idle, red while recording, amber while the text is in
+flight; `rpm` turns red at the limit, where a take would be refused.
+
+![Footer indicator](assets/footer.png)
+
+While a take is running the prompt footer carries a red `● REC Ns`; it turns amber
+while the text is in flight.
+
+![Quota dialog](assets/quota.png)
+
+The quota dialog, also reachable by clicking `today`, `total` or `rpm`: model, language,
+requests left today (from the Groq headers), local RPM, spend today with the number of
+takes, spend in total.
+
+## Cost and quota
+
+- Cost is estimated on the audio length at **$0.04/hour** and appended to
+  `~/.cache/groq-dictate-costs.log`, the same file and the same four columns
+  (`date time seconds cost`) the older shell script wrote, so a `/dictate-cost` command
+  keeps working unchanged.
+- The **daily** request figure comes from the `x-ratelimit-*` headers of the real
+  transcription. No request is spent just to read the quota.
+- The **per-minute** figure is tracked locally: timestamps of the last 60 seconds, cap
+  20, the free tier limit. At the cap the recording does not start.
+- Language defaults to Italian. Set another ISO code, or `auto` for detection, from the
+  language dialog. Model can be `whisper-large-v3-turbo` (default, faster) or
+  `whisper-large-v3` (same price, a little more accurate).
+
+## How it works
+
+1. `parec --rate=16000 --channels=1 --file-format=wav` records to `/tmp` at the rate
+   Whisper wants, so no `ffmpeg` step is needed.
+2. On stop the WAV goes to `https://api.groq.com/openai/v1/audio/transcriptions` with
+   `fetch` and `FormData` (no dependencies), and the file is deleted as soon as the
+   answer arrives.
+3. The text goes to the clipboard with `xclip`, then `prompt.paste` puts it in the
+   composer.
+4. The cost line is appended and the sidebar totals update.
+
+The pure logic (`src/voice.ts`: audio length, cost, log format, rpm window, totals) is
+separate from the TUI so it can be unit tested without a terminal.
+
+## Limitations
+
+- TUI only: dictating into a browser or an editor is out of scope. A desktop shortcut
+  running a small script is still the right tool there.
+- The transcript is pasted, not submitted: you always get a chance to fix it.
+- No automatic stop at the end of a sentence yet. The microphone gain on a typical
+  laptop is too high for a threshold to separate voice from room; see [TODO.md](TODO.md)
+  for the measurements and the sketch.
+- A silent or monitor source makes Whisper hallucinate ("Grazie a tutti!" is the
+  classic). The plugin checks `pactl get-default-source` and refuses to record when the
+  default is a `.monitor`; if the check passes and the text still looks invented, the
+  capture level is the first thing to look at.
+
+## Development
+
+```bash
+bun test                          # unit tests on the pure logic
+bun build tui.tsx --target=node --external '*'   # type/JSX sanity check
+```
+
+The plugin is one TUI entry point (`tui.tsx`) plus one pure module (`src/voice.ts`).
+Editing it requires restarting the TUI: there is no hot reload.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "opencode-groq-dictate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.2",
+  "description": "Groq dictation in the OpenCode v2 TUI: alt+v records, transcribes with whisper-large-v3-turbo, and pastes the text into the prompt.",
+  "private": false,
+  "type": "module",
+  "exports": {
+    "./tui": "./tui.tsx"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "files": [
+    "tui.tsx",
+    "src"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tui",
+    "dictation",
+    "groq",
+    "whisper"
+  ],
+  "license": "MIT",
+  "author": "Leonardo Cosmai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LeonVeganMan/opencode-groq-dictate.git"
+  },
+  "homepage": "https://github.com/LeonVeganMan/opencode-groq-dictate#readme"
+}

package/src/voice.test.ts

@@ -0,0 +1,70 @@
+import { expect, test } from "bun:test"
+import {
+  DEFAULT_MODEL,
+  audioSeconds,
+  cost,
+  logLine,
+  parseConfig,
+  recentRpm,
+  startTicker,
+  summarize,
+} from "./voice"
+
+test("audio length comes from the bytes past the header", () => {
+  expect(audioSeconds(44)).toBe(0)
+  expect(audioSeconds(44 + 16_000 * 2 * 3)).toBe(3)
+})
+
+test("cost is the hourly rate pro rata", () => {
+  expect(cost(3600)).toBeCloseTo(0.04, 6)
+  expect(cost(0)).toBe(0)
+})
+
+test("the rpm window drops stamps older than a minute", () => {
+  const now = 100_000
+  expect(recentRpm([now - 61_000, now - 1_000, now], now)).toEqual([now - 1_000, now])
+})
+
+test("a config with the wrong types falls back to the defaults", () => {
+  expect(parseConfig(null)).toEqual({ apiKey: "", language: "it", model: DEFAULT_MODEL })
+  expect(parseConfig({ apiKey: 42, language: "", model: "nope" })).toEqual({
+    apiKey: "",
+    language: "it",
+    model: DEFAULT_MODEL,
+  })
+  expect(parseConfig({ apiKey: "gsk_x", language: "auto", model: "whisper-large-v3" })).toEqual({
+    apiKey: "gsk_x",
+    language: "auto",
+    model: "whisper-large-v3",
+  })
+})
+
+test("the cost line keeps the shell script's four columns", () => {
+  expect(logLine(new Date(2026, 9, 19, 8, 5, 3), 12.34, 0.000137)).toBe("2026-10-19 08:05:03 12.3 0.000137")
+})
+
+test("the totals only count today's lines, and ignore junk", () => {
+  const now = new Date(2026, 9, 19, 12, 0, 0)
+  const log = [
+    "2026-10-18 16:30:57 453.7 0.005041",
+    "2026-10-19 08:05:03 12.3 0.000137",
+    "2026-10-19 09:00:00 30.0 0.000333",
+    "garbage line",
+    "",
+  ].join("\n")
+  const totals = summarize(log, now)
+  expect(totals.today).toBeCloseTo(0.00047, 9)
+  expect(totals.total).toBeCloseTo(0.005511, 9)
+  expect(totals.todayCount).toBe(2)
+})
+
+test("the ticker runs until its stop function is called", async () => {
+  let ticks = 0
+  const stop = startTicker(() => ticks++, 5)
+  await new Promise((done) => setTimeout(done, 22))
+  stop()
+  const seen = ticks
+  await new Promise((done) => setTimeout(done, 20))
+  expect(seen).toBeGreaterThan(0)
+  expect(ticks).toBe(seen)
+})

package/src/voice.ts

@@ -0,0 +1,78 @@
+// The parts of dictation that do not touch a terminal: config shape, WAV maths,
+// the local RPM window, the cost-log line and the totals read back from it.
+// Kept here so `bun test` can check them without the TUI.
+
+export const MODELS = ["whisper-large-v3-turbo", "whisper-large-v3"] as const
+export type Model = (typeof MODELS)[number]
+export const DEFAULT_MODEL: Model = "whisper-large-v3-turbo"
+// Both models bill the same per audio hour; turbo is only faster.
+export const USD_PER_HOUR = 0.04
+export const RPM_LIMIT = 20
+// A forgotten recording would upload silence for minutes; cap it.
+export const MAX_SECONDS = 60
+export const SAMPLE_RATE = 16_000
+export const BYTES_PER_SAMPLE = 2
+// parec writes a canonical 44-byte header; anything past it is audio.
+export const WAV_HEADER = 44
+
+export type Config = { apiKey: string; language: string; model: Model }
+
+export const DEFAULTS: Config = { apiKey: "", language: "it", model: DEFAULT_MODEL }
+
+export function parseConfig(raw: unknown): Config {
+  const value = (raw ?? {}) as Record<string, unknown>
+  const model = MODELS.includes(value.model as Model) ? (value.model as Model) : DEFAULTS.model
+  return {
+    apiKey: typeof value.apiKey === "string" ? value.apiKey : DEFAULTS.apiKey,
+    language: typeof value.language === "string" && value.language ? value.language : DEFAULTS.language,
+    model,
+  }
+}
+
+export function audioSeconds(bytes: number): number {
+  return Math.max(0, bytes - WAV_HEADER) / (SAMPLE_RATE * BYTES_PER_SAMPLE)
+}
+
+export function cost(seconds: number): number {
+  return (seconds / 3600) * USD_PER_HOUR
+}
+
+export function recentRpm(stamps: number[], now: number): number[] {
+  return stamps.filter((at) => now - at < 60_000)
+}
+
+// Same columns the shell script wrote: `date time seconds cost`, which is what
+// the /dictate-cost command's awk still reads.
+export function logLine(at: Date, seconds: number, usd: number): string {
+  const pad = (n: number) => String(n).padStart(2, "0")
+  const date = `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())}`
+  const time = `${pad(at.getHours())}:${pad(at.getMinutes())}:${pad(at.getSeconds())}`
+  return `${date} ${time} ${seconds.toFixed(1)} ${usd.toFixed(6)}`
+}
+
+export type Totals = { today: number; total: number; todayCount: number }
+
+// Reads back the same four columns, ignoring anything malformed so a hand-edited
+// log line cannot break the sidebar.
+export function summarize(text: string, now: Date): Totals {
+  const pad = (n: number) => String(n).padStart(2, "0")
+  const today = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`
+  const totals: Totals = { today: 0, total: 0, todayCount: 0 }
+  for (const line of text.split("\n")) {
+    const [date, , , rawCost] = line.trim().split(/\s+/)
+    const usd = Number(rawCost)
+    if (!date || !Number.isFinite(usd)) continue
+    totals.total += usd
+    if (date === today) {
+      totals.today += usd
+      totals.todayCount += 1
+    }
+  }
+  return totals
+}
+
+// One ticker for the recording counter: the TUI only supplies the signal.
+export function startTicker(onTick: () => void, ms = 1000): () => void {
+  const id = setInterval(onTick, ms)
+  return () => clearInterval(id)
+}

package/tui.tsx

@@ -0,0 +1,433 @@
+/** @jsxImportSource @opentui/solid */
+import { execFile, spawn } from "node:child_process"
+import { readFile, appendFile, rm, stat } from "node:fs/promises"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { Show, createMemo, createSignal } from "solid-js"
+import { Plugin } from "@opencode/plugin/tui"
+import {
+  DEFAULTS,
+  MAX_SECONDS,
+  MODELS,
+  RPM_LIMIT,
+  audioSeconds,
+  cost,
+  logLine,
+  parseConfig,
+  recentRpm,
+  startTicker,
+  summarize,
+} from "./src/voice"
+
+const WAV = "/tmp/opencode-groq-dictate.wav"
+const COST_LOG = join(homedir(), ".cache/groq-dictate-costs.log")
+const GROQ_URL = "https://api.groq.com/openai/v1/audio/transcriptions"
+// Same column width as the go-meter panel, so both plugins line up.
+const LABEL_WIDTH = 8
+
+// super+v is the key the shell script used; here the recording, the upload and the
+// paste all stay inside the TUI, so nothing depends on which window has focus.
+export default Plugin.define({
+  id: "opencode-groq-dictate",
+  setup(context) {
+    // The docs show the first element used as a value, other plugins read it as an
+    // accessor; accepting both keeps the plugin working whichever it is.
+    const read = <T,>(value: T | (() => T)): T =>
+      typeof value === "function" ? (value as () => T)() : value
+
+    const [config, updateConfig] = context.storage.store("opencode-groq-dictate", { initial: DEFAULTS })
+    const [rpm, updateRpm] = context.storage.memory("opencode-groq-dictate.rpm", { initial: [] as number[] })
+    const [quota, updateQuota] = context.storage.memory("opencode-groq-dictate.quota", {
+      initial: { remaining: 0, limit: 0 },
+    })
+    let recorder: ReturnType<typeof spawn> | null = null
+    // A signal, not a plain variable: the footer indicator has to re-render when
+    // it flips, and a call still reads the current value inside a command.
+    const [recording, setRecording] = createSignal(false)
+    const [elapsed, setElapsed] = createSignal(0)
+    // "busy" covers the gap between stop and paste, so the dot never blinks off.
+    const [busy, setBusy] = createSignal(false)
+    const [totals, setTotals] = createSignal({ today: 0, total: 0, todayCount: 0 })
+    const [last, setLast] = createSignal<{ seconds: number; usd: number } | null>(null)
+    let ticker: (() => void) | null = null
+    let autoStop: ReturnType<typeof setTimeout> | null = null
+
+    const settings = () => parseConfig(read(config))
+
+    // Seeded from the log the shell script already wrote, so the sidebar shows the
+    // real spend from the first run instead of starting at zero.
+    void readFile(COST_LOG, "utf8")
+      .then((text) => setTotals(summarize(text, new Date())))
+      .catch(() => {})
+
+    async function askKey() {
+      const apiKey = await context.ui.dialog.prompt({
+        title: "Groq API key",
+        placeholder: "gsk_...",
+      })
+      if (!apiKey) return ""
+      await updateConfig((draft) => {
+        draft.apiKey = apiKey.trim()
+      })
+      return apiKey.trim()
+    }
+
+    async function paste(text: string) {
+      // prompt.paste reads the system clipboard, so the text goes there first and
+      // the composer receives it exactly as if it had been pasted by hand.
+      const clip = spawn("xclip", ["-selection", "clipboard"], { stdio: ["pipe", "ignore", "ignore"] })
+      clip.stdin.end(text)
+      await new Promise((done) => clip.on("close", done))
+      context.keymap.dispatch("prompt.paste")
+    }
+
+    // One round trip to Groq. Returns the text, or why there is none, so the
+    // caller does not have to read the response twice.
+    async function request(key: string, model: string, language: string) {
+      const bytes = await readFile(WAV)
+      const form = new FormData()
+      form.append("file", new Blob([bytes], { type: "audio/wav" }), "voice.wav")
+      form.append("model", model)
+      if (language !== "auto") form.append("language", language)
+
+      const response = await fetch(GROQ_URL, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${key}` },
+        body: form,
+      })
+
+      // The daily figure only ever arrives as a header, so it is read off the real
+      // request instead of spending a transcription on a probe.
+      const remaining = Number(response.headers.get("x-ratelimit-remaining-requests"))
+      const limit = Number(response.headers.get("x-ratelimit-limit-requests"))
+      if (limit > 0)
+        await updateQuota((draft) => {
+          draft.remaining = remaining
+          draft.limit = limit
+        })
+
+      if (response.status === 401) {
+        await updateConfig((draft) => {
+          draft.apiKey = ""
+        })
+        return { error: "Groq API key rejected" }
+      }
+      if (!response.ok) return { error: `Groq ${response.status}: ${await response.text()}` }
+
+      const text = ((await response.json()) as { text?: string }).text?.trim()
+      return text ? { text } : { warning: "Nothing transcribed" }
+    }
+
+    // Cost bookkeeping: the log line is best effort, the totals are in memory.
+    async function bookkeep(seconds: number) {
+      const usd = cost(seconds)
+      try {
+        await appendFile(COST_LOG, logLine(new Date(), seconds, usd) + "\n")
+      } catch (error) {
+        context.ui.toast.show({ message: `Cost log: ${String(error)}`, variant: "warning" })
+      }
+      setTotals((current) => ({
+        today: current.today + usd,
+        total: current.total + usd,
+        todayCount: current.todayCount + 1,
+      }))
+      setLast({ seconds, usd })
+      return usd
+    }
+
+    async function transcribe(seconds: number) {
+      const { apiKey, language, model } = settings()
+      const key = apiKey || (await askKey())
+      if (!key) return
+
+      const outcome = await request(key, model, language)
+      if (outcome.error) {
+        context.ui.toast.show({ message: outcome.error, variant: "error" })
+        return
+      }
+      if (!outcome.text) {
+        context.ui.toast.show({ message: outcome.warning ?? "Nothing transcribed", variant: "warning" })
+        return
+      }
+
+      await paste(outcome.text)
+      // The recording is only needed until Groq answers; leaving it in /tmp keeps
+      // a copy of everything dictated on disk.
+      await rm(WAV, { force: true }).catch(() => {})
+
+      const usd = await bookkeep(seconds)
+      context.ui.toast.show({ message: `Dictated ${seconds.toFixed(1)}s · $${usd.toFixed(4)}`, variant: "success" })
+    }
+
+    async function stop() {
+      if (!recorder) return
+      const child = recorder
+      recorder = null
+      setRecording(false)
+      setBusy(true)
+      ticker?.()
+      if (autoStop) clearTimeout(autoStop)
+      ticker = null
+      autoStop = null
+      child.kill("SIGINT")
+      await new Promise((done) => child.on("close", done))
+      const seconds = audioSeconds((await stat(WAV)).size)
+      if (seconds < 0.2) {
+        context.ui.toast.show({ message: "Recording too short", variant: "warning" })
+        setBusy(false)
+        return
+      }
+      context.ui.toast.show({ message: "Transcribing…", variant: "info" })
+      try {
+        await transcribe(seconds)
+      } catch (error) {
+        context.ui.toast.show({ message: String(error), variant: "error" })
+      } finally {
+        setBusy(false)
+      }
+    }
+
+    // A monitor source records the speakers, not the room: that silence comes back as
+    // an invented sentence ("Grazie a tutti!"), so the take is refused before it starts.
+    const hasMicrophone = () =>
+      new Promise<boolean>((done) => {
+        execFile("pactl", ["get-default-source"], (error, stdout) =>
+          done(!!error || !stdout.trim().endsWith(".monitor")),
+        )
+      })
+
+    async function start() {
+      const { apiKey } = settings()
+      if (!apiKey) {
+        context.ui.toast.show({ message: "Set the Groq API key first", variant: "warning" })
+        if (!(await askKey())) return
+      }
+      if (!(await hasMicrophone())) {
+        context.ui.toast.show({
+          message: "No microphone: the default source is a monitor",
+          variant: "error",
+        })
+        return
+      }
+      const now = Date.now()
+      const recent = recentRpm(read(rpm), now)
+      if (recent.length >= RPM_LIMIT) {
+        context.ui.toast.show({ message: `Groq free tier: ${RPM_LIMIT}/min reached, wait a moment`, variant: "error" })
+        return
+      }
+      await updateRpm((draft) => {
+        draft.splice(0, draft.length, ...recent, now)
+      })
+
+      recorder = spawn("parec", ["--rate=16000", "--channels=1", "--file-format=wav", WAV], {
+        stdio: "ignore",
+      })
+      recorder.on("error", (error) => {
+        recorder = null
+        setRecording(false)
+        setBusy(false)
+        ticker?.()
+        if (autoStop) clearTimeout(autoStop)
+        context.ui.toast.show({ message: `parec: ${error.message}`, variant: "error" })
+      })
+      setRecording(true)
+      setElapsed(0)
+      ticker = startTicker(() => setElapsed((value) => value + 1))
+      // Nobody wants a ten-minute upload because the stop key was forgotten.
+      autoStop = setTimeout(() => {
+        context.ui.toast.show({ message: `Stopped at ${MAX_SECONDS}s`, variant: "warning" })
+        void stop()
+      }, MAX_SECONDS * 1000)
+      context.ui.toast.show({ message: "Recording… alt+v stop · esc cancel", variant: "info", duration: 2000 })
+    }
+
+
+    // Esc aborts the take: nothing is uploaded, so no quota and no cost.
+    async function cancel() {
+      if (!recorder) return
+      const child = recorder
+      recorder = null
+      setRecording(false)
+      setBusy(false)
+      ticker?.()
+      ticker = null
+      if (autoStop) clearTimeout(autoStop)
+      autoStop = null
+      child.kill("SIGINT")
+      await new Promise((done) => child.on("close", done))
+      await rm(WAV, { force: true }).catch(() => {})
+      context.ui.toast.show({ message: "Recording cancelled", variant: "info" })
+    }
+
+    // One entry point for the keybinding and for the click on the panel.
+
+    const toggle = () => (recording() ? stop() : start())
+
+    async function pickModel() {
+      const model = await context.ui.dialog.select({
+        title: "Transcription model",
+        options: MODELS.map((id) => ({ value: id, title: id })),
+      })
+      if (!model) return
+      await updateConfig((draft) => {
+        draft.model = model
+      })
+      context.ui.toast.show({ message: `Model: ${model}`, variant: "success" })
+    }
+
+    async function showQuota() {
+      const { remaining, limit } = read(quota)
+      const used = recentRpm(read(rpm), Date.now()).length
+      const { today, total, todayCount } = read(totals)
+      await context.ui.dialog.alert({
+        title: "Groq dictation",
+        message: [
+          `Model: ${settings().model}`,
+          `Language: ${settings().language}`,
+          `Requests today: ${limit > 0 ? `${remaining} / ${limit} left` : "unknown (dictate once)"}`,
+          `Local RPM: ${used} / ${RPM_LIMIT}`,
+          `Spent today: $${today.toFixed(4)} (${todayCount} runs)`,
+          `Spent in total: $${total.toFixed(4)}`,
+        ].join("\n"),
+      })
+    }
+
+    async function pickLanguage() {
+      const language = await context.ui.dialog.prompt({
+        title: "Language code (blank or 'auto' for detection)",
+        placeholder: settings().language,
+      })
+      if (language === undefined) return
+      await updateConfig((draft) => {
+        draft.language = language.trim() || "auto"
+      })
+      context.ui.toast.show({ message: `Language: ${settings().language}`, variant: "success" })
+    }
+
+    context.keymap.layer(() => ({
+      mode: "global",
+      priority: 10,
+      commands: [
+        {
+          id: "opencode-groq-dictate.toggle",
+          title: "Dictate (Groq)",
+          group: "Voice",
+          // Not super+v: VTE only enables xterm modifyOtherKeys, which never
+          // reports the Super modifier, so that binding could not fire here.
+          bind: "alt+v",
+          palette: true,
+          slash: { name: "dictate" },
+          run: toggle,
+        },
+        {
+          id: "opencode-groq-dictate.cancel",
+          title: "Cancel dictation",
+          group: "Voice",
+          bind: "escape",
+          // Returning false hands Escape back to the TUI when nothing is recording.
+          run: () => {
+            if (!recorder) return false
+            void cancel()
+            return true
+          },
+        },
+        {
+          id: "opencode-groq-dictate.quota",
+          title: "Dictation quota",
+          group: "Voice",
+          palette: true,
+          run: showQuota,
+        },
+        {
+          id: "opencode-groq-dictate.language",
+          title: "Dictation language",
+          group: "Voice",
+          palette: true,
+          run: pickLanguage,
+        },
+        {
+          id: "opencode-groq-dictate.model",
+          title: "Dictation model",
+          group: "Voice",
+          palette: true,
+          run: pickModel,
+        },
+      ],
+      bindings: ["opencode-groq-dictate.toggle", "opencode-groq-dictate.cancel"],
+    }))
+
+    const red = () => context.theme?.hue?.red?.["400"] ?? "#ff5555"
+    const amber = () => context.theme?.hue?.orange ?? "#FF9654"
+    const green = () => context.theme?.hue?.green?.["400"] ?? "#7fbf7f"
+    const muted = () => context.theme?.text?.muted ?? context.theme?.text?.subdued ?? "#808080"
+    // The brand accent, the same one the go-meter panel uses for its figures.
+    const accent = () =>
+      context.theme?.hue?.accent?.["500"] ?? context.theme?.hue?.interactive?.["300"] ?? "#FF9654"
+
+    // The footer row already carries the model and the other status items, so the
+    // dot sits next to them and disappears when there is nothing to report.
+    context.ui.slot({
+      append: "prompt.footer.status",
+      render: () => (
+        <Show when={recording() || busy()}>
+          <text fg={recording() ? red() : amber()}>
+            {recording() ? `● REC ${elapsed()}s` : "● …"}
+          </text>
+        </Show>
+      ),
+    })
+
+    // Label column, the same width trick the go-meter rows use so the figures line
+    // up under each other instead of drifting.
+    const row = (label: string, value: string, fg: () => string | undefined, onClick?: () => void) => (
+      <box flexDirection="row" gap={0} onMouseUp={onClick}>
+        <text>{label.padEnd(LABEL_WIDTH)}</text>
+        <text fg={fg()}>{value}</text>
+      </box>
+    )
+
+    // Memoised so the six rows do not recompute the log totals on every repaint.
+    const spent = createMemo(() => read(totals))
+    const lastRun = createMemo(() => last())
+
+    // Same slot the go-meter plugin uses: the sidebar is where a figure can sit
+    // without crowding the prompt row.
+    context.ui.slot({
+      append: "sidebar.content",
+      render: () => {
+        const figures = spent()
+        const used = recentRpm(read(rpm), Date.now()).length
+        // Three colours, one meaning each: red while recording, amber while the
+        // text is in flight, green when the plugin is idle and ready.
+        const state = () => (recording() ? red() : busy() ? amber() : green())
+        return (
+          <box flexDirection="column">
+            <text fg={muted()} onMouseUp={toggle}>
+              Groq Dictate
+            </text>
+            {row(
+              "state",
+              recording() ? `● rec ${elapsed()}s` : busy() ? "transcribing…" : "idle",
+              state,
+              toggle,
+            )}
+            {row("model", settings().model.replace("whisper-", ""), () => undefined, pickModel)}
+            {row("lang", settings().language, () => undefined, pickLanguage)}
+            {row("today", `$${figures.today.toFixed(4)} · ${figures.todayCount}`, accent)}
+            {row("total", `$${figures.total.toFixed(4)}`, accent)}
+            <Show when={lastRun()}>
+              {(run) => row("last", `${run().seconds.toFixed(1)}s · $${run().usd.toFixed(4)}`, muted)}
+            </Show>
+            {row("rpm", `${used}/${RPM_LIMIT}`, used >= RPM_LIMIT ? red : muted, showQuota)}
+          </box>
+        )
+      },
+    })
+
+    return () => {
+      ticker?.()
+      if (autoStop) clearTimeout(autoStop)
+      if (recorder) recorder.kill("SIGINT")
+    }
+  },
+})