OpenCode Talk

A voice interface for OpenCode - talk to your codebase naturally.

Status: Active development. Core functionality works but expect rough edges. See Known Issues below.

Installation

Prerequisites

You need these installed first:

Requirement	Check if installed	Install
Homebrew	`brew --version`	brew.sh
Node.js 18+	`node --version`	`brew install node`
Rust	`rustc --version`	`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh`
OpenCode	`opencode --version`	`npm install -g opencode` or see opencode.ai

Build & Run

# Clone and build
git clone https://github.com/dcartertwo/opencode-talk.git
cd opencode-talk
npm install
npm run tauri build

# The app is now at:
# src-tauri/target/release/bundle/macos/OpenCode Talk.app
#
# Drag it to /Applications or run directly:
open "src-tauri/target/release/bundle/macos/OpenCode Talk.app"

Build failing? See Troubleshooting below.

Setup

Step 1: Start OpenCode (Required)

In a terminal, navigate to your project and start the OpenCode server:

cd ~/your-project
opencode serve

Keep this terminal open. OpenCode Talk connects to this server.

Step 2: Launch OpenCode Talk

Open the app. You should see "Connected" in the status bar. If not, check that OpenCode is running.

Step 3: Configure Voice Output

Choose one option:

Option A: macOS Say (Zero Setup - Works Immediately)

Open Settings (gear icon)
Set TTS Engine to macos
Done! Test by sending a message.

This uses the built-in macOS say command. Quality is basic but it works out of the box.

Option B: Kokoro (Best Quality - Recommended)

Kokoro provides natural, high-quality voices but requires Python setup.

# Install Python dependencies
pip3 install kokoro soundfile numpy

# Install phoneme processor (required by Kokoro)
brew install espeak-ng

# Verify installation
python3 -c "from kokoro import KPipeline; print('Kokoro OK')"

Expected output: Kokoro OK

If you see errors:

No module named 'kokoro' → Run pip3 install kokoro again
espeak not found → Run brew install espeak-ng again

In the app:

Open Settings
Set TTS Engine to kokoro
Set Voice to af_heart (or another Kokoro voice)
First message will take ~5 seconds (model loading), then ~0.3s per sentence

Step 4: Configure Voice Input

Choose one option:

Option A: Type Only (Zero Setup)

Just type in the text box and press Enter. Skip this section entirely.

Option B: macOS Dictation (Easy Setup)

System Settings → Keyboard → Dictation → Turn On
Press the dictation key (default: double-tap Fn) anywhere to speak
macOS will type what you say into the OpenCode Talk input box

Option C: SuperWhisper (Best Quality - Recommended)

SuperWhisper provides the best transcription quality with local processing.

Install SuperWhisper from superwhisper.com ($8/month or lifetime)
Install Macrowhisper (bridges SuperWhisper to apps):
```
brew install ognistik/formulae/macrowhisper
```
Configure SuperWhisper (important!):
- Open SuperWhisper preferences
- Turn OFF: "Paste Result Text"
- Turn OFF: "Restore Clipboard After Paste"
- Turn OFF: "Simulate Key Presses"
- Keep ON: "Recording Window"
Start Macrowhisper service:
```
macrowhisper --start-service
```
In OpenCode Talk Settings, click "Auto-Configure" or verify the transcription server is receiving.
Test: Press Option+Space to speak. Your transcription should appear in the input box.

Verify Everything Works

Test	Expected Result
App launches	Spinner in status bar while preparing
Status shows "⌥Space ready"	Hotkey registered successfully
"Ready for voice input" toast	All systems operational
Status shows "Connected"	OpenCode server is running
Type a message, press Enter	Response appears + audio plays
Audio plays	You hear the response spoken

If voice input is configured:

Test	Expected Result
Press Option+Space and speak	Your words appear in input box
Press Enter	Response with audio

Status Bar Indicators

The status bar shows real-time system status:

Spinner - App is preparing (connecting, registering hotkeys)
⌥Space ready (green) - Hotkey registered and ready for voice input
⌥Space ⚠️ (red) - Hotkey registration failed (hover for details)
TTS engine name - Shows active TTS engine (Kokoro, Piper, etc.)

Troubleshooting

Build Issues

npm install fails with node-gyp errors:

# Install Xcode command line tools
xcode-select --install

npm run tauri build fails with Rust errors:

# Update Rust
rustup update

# If still failing, try:
cd src-tauri
cargo build --release

Build succeeds but app won't open:

# Check for quarantine attribute
xattr -d com.apple.quarantine "src-tauri/target/release/bundle/macos/OpenCode Talk.app"

Connection Issues

"Not connected to OpenCode":

Make sure OpenCode is running: opencode serve
Check the port: default is http://localhost:4096
Check Settings → OpenCode → Server URL

TTS Issues

No audio with Kokoro:

# Test Kokoro directly
python3 -c "
from kokoro import KPipeline
import soundfile as sf
import numpy as np
pipe = KPipeline(lang_code='a')
audio = list(pipe('Hello world', voice='af_heart', speed=1.2))
if audio:
    print('Kokoro working!')
"

Kokoro fails with espeak error:

brew install espeak-ng

Fall back to macOS: In Settings, set TTS Engine to macos. This always works.

Voice Input Issues

SuperWhisper not sending to app:

Check Macrowhisper is running: macrowhisper --service-status
Restart it: macrowhisper --stop-service && macrowhisper --start-service
Check SuperWhisper settings (see Step 4 above)

Hotkeys not working:

System Settings → Privacy & Security → Accessibility
Add OpenCode Talk to the list
Restart the app

Hotkey shows red warning icon (⚠️):

The status bar shows a red warning icon next to the hotkey if registration failed:

Conflict with another app - Another app may have the same hotkey registered
- Check SuperWhisper, Alfred, Raycast, or similar apps using Option+Space
- Change the hotkey in OpenCode Talk Settings
Accessibility permission needed
- System Settings → Privacy & Security → Accessibility
- Add/enable OpenCode Talk
Restart the app after changing settings or permissions

Usage

Menu Bar App

OpenCode Talk runs as a menu bar app:

Close window (⌘W or red X) - Hides the window, app stays running in menu bar
Quit app (⌘Q) - Fully quits the application
Tray icon - Click to show/hide the main window, right-click for menu

To fully quit, use ⌘Q or right-click the tray icon and select "Quit OpenCode Talk".

Hotkeys

Action	Hotkey
Push-to-Talk	`Option + Space`
Continuous Mode	`Option + Shift + Space`
Interrupt/Stop	`Escape`

Voice Commands

"New conversation" - Clear history and start fresh
"Yes" / "No" - Respond to confirmation prompts

Development

# Run in dev mode (hot reload)
npm run tauri dev

# Build for production
npm run tauri build

# Type check
npm run build

See AGENTS.md for architecture documentation. See CONTRIBUTING.md for contribution guidelines.

Known Issues

Current limitations and work in progress:

Issue	Status	Workaround
Kokoro TTS server must be running separately	Planned	Falls back to Piper/macOS automatically

Recent Improvements (v0.1.3)

Readiness indicators - Status bar shows when app is ready for voice input
Hotkey status - Visual confirmation that hotkey is registered and working
TTS engine display - Shows active TTS engine (with fallback indicator)
"Ready" toast - Notification when all systems are operational

Previous Improvements (v0.1.2)

Zero-gap audio playback - Replaced afplay subprocess with rodio for seamless sentence transitions
No more orphan processes - Audio runs in-process, no external processes to track/kill
Better connection handling - Visual Wifi/WifiOff indicator, "Connecting..." state
Toast notifications - Errors and warnings now show as dismissible toasts
Request cancellation - Properly aborts in-flight requests when stopping
Confirmation timeout - Pending confirmations auto-cancel after 30 seconds
Incomplete response warning - Messages show warning if response was cut off

Why OpenCode Talk?

Hands-free - Talk while sketching, pacing, or keeping hands on keyboard
Lower friction - Speak naturally instead of typing prompts
Real-time - Streaming text + voice creates natural dialogue
Privacy - Local TTS keeps conversations on your machine

License

MIT

Credits

OpenCode - AI coding agent
Kokoro - High-quality local TTS
SuperWhisper - Voice-to-text
Tauri - App framework

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
.vscode		.vscode
public		public
src-tauri		src-tauri
src		src
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

dcartertwo/opencode-talk

Folders and files

Latest commit

History

Repository files navigation