?FAQ Everyone
Is my spoken data sent to any external service?
No, the voice processing stays on your machine, so neither speech‑to‑text nor text‑to‑speech leaves your device.
Track 13 · Advanced
13.2.8.1
opencode + voice
Hands-free, fully local — drive the open agent by voice
1Overview
A community-built (not official SST/Anomaly) voice layer for opencode — local speech-to-text in, a plugin-driven local text-to-speech "speak" tool out.
Voice-control opencode: a community stack that lets you talk to the open-source terminal agent and hear it reply, with speech-to-text and text-to-speech both running on hardware you own. The listening half (local Whisper) runs on any CPU; the talking-back half plugs into opencode through its plugin system. Not official SST tooling — three open-source pieces glued together.
1.1Before you start
1.2After this chapter you can
→Trace the mic → Whisper → opencode → speak-tool → TTS pipeline and its honest privacy scope
→Install opencode-voice and drive opencode hands-free with local, CPU-only speech-to-text
→Add a 'speak' tool via opencode's plugin system, using a laptop-friendly local voice (Piper)
1.3Best for
Hands-free coding sessions and privacy-sensitive work — reviewing or fixing code by voice without your spoken words hitting a third-party server.
1.4Watch out
Voice cloning needs a real GPU (~10GB VRAM); the stack is three separately-maintained unofficial repos glued together; and "local" describes the voice layer only — the LLM opencode calls may still be a cloud API.
1.5Free vs paid
Every piece is open-source and free — you only supply the compute (a CPU is enough for listening; a GPU helps for voice cloning).
2Lessons 3
2.1 Set up voice input and output in OpenCode
The Whisper STT binary provides local speech‑to‑text functionality used by OpenCode’s voice features.
Configure Whisper STT, the speak plugin, and a local TTS model for hands‑free interaction
- Clone the git clone command of the opencode-voice repository into your development folder
- Run the cargo run --release command of the Rust installer to build and install the local Whisper STT binary
- Copy the speak plugin directory into OpenCode’s plugins/ folder using your file manager or terminal
- Download a compatible local TTS model and place it in the path expected by the speak plugin
- You'll see The CLI displays ‘Listening…’ and the console lists a new tool named
speak - Takeaway Voice integrates local speech‑to‑text, a plug‑in, and text‑to‑speech to run AI without external services
- Check What output in the CLI confirms that voice integration has been set up correctly after following the installation steps?
2.2 Run OpenCode using voice commands
The speak plugin converts transcribed speech into prompts that OpenCode can execute.
Speak a command and have OpenCode process the transcription as a prompt
- Execute /plugins list in an OpenCode session
- Edit the speak plugin configuration to set the Whisper path
- Enter !speak start in the terminal
- Speak your request, e.g., create a README file
- You'll see The spoken sentence appears as transcribed text and OpenCode processes it
- Takeaway A speech‑to‑text plugin turns voice into actionable prompts for hands‑free coding
- Check How does OpenCode show that your spoken request has been turned into a prompt after running !speak start?
2.3 Make OpenCode speak its answers
The tts_model_path field points to the directory of the local text‑to‑speech model used for audio playback.
Hear OpenCode’s answers spoken aloud using the local TTS model
- Open Speak Plugin Settings and locate the tts_model_path field
- Enter the path to your local model directory in the tts_model_path field
- Run the command !speak enable-audio in an OpenCode session
- Submit a question that generates a multi‑sentence answer
- Hear the synthesized speech play through your speakers
- You'll see Audio playback matches the text response in the chat window
- Takeaway Plugins let you combine STT and TTS for a private, interchangeable voice loop
- Check What evidence do you see that the local TTS model is successfully speaking OpenCode’s multi‑sentence answer after enabling audio?
3You’ll know it worked 62 checkable outcomes in this chapter
- ✓Typing 'opencode' shows the interactive prompt instead of 'command not found'
- ✓Opening agents.md shows sections like Repository Rule, Agent Rule, Folder Map, and Skills list
- ✓The corresponding UI element is added/removed in the running app after the command completes
- ✓Read the generated report; it should mention high load average, long uptime, resource‑heavy apps, etc.
- ✓The app displays three draggable columns and tasks can be moved between them
- ✓When in plan mode the agent asks for confirmation before edits; in build mode changes are applied automatically.
- ✓The output shows detected issues; after asking to fix, the code updates accordingly
- ✓Running '/skills' lists the newly installed skill
62 outcomes in all — one per recipe below.
4FAQ, Tips & How-to 67
one problem, one solution, one action
?FAQ Everyone
How can I verify where the voice data is processed?
You can trace the end‑to‑end flow in your mind: the pipeline runs entirely on‑device, and you can map each step to see that no third‑party transmission occurs.
?FAQ Everyone
Do I have to pay for using opencode-voice?
The software itself is free and open source; the only cost is the compute resources (CPU/GPU) you already have available.
?FAQ Everyone
Can I run the voice plugin locally without internet?
Yes, you can clone the repository, install dependencies, and build it into a local `index.js` file that runs on your machine.
?FAQ Everyone
How do I get speech synthesis to work on CPU only?
Configure the plugin’s speak tool to point at Piper’s HTTP endpoint or local script; Piper provides a backend that runs entirely on the CPU.
Terminal doesn’t recognize the new command
Run the curl command from opencode.ai in a terminal, then restart or open a new shell so the 'opencode' command is recognized. This sets up the OpenCode binary on your PATH.
Need to change the AI model you’re using
Use the '/connect' command inside OpenCode to list providers, then paste an API key or select a built‑in subscription model. This lets one agent work with any LLM you have access to.
Want a ready‑made NestJS hello‑world server
Ask OpenCode to scaffold code by describing the target project. The agent writes files, installs dependencies, and you can run the result immediately.
Need separate work streams without losing context
OpenCode supports parallel sessions via the '/new' and '/sessions' commands. You can pause, continue, or fork a session at any point, enabling separate workflows like refactoring vs documentation.
The '/share' command generates a public HTML URL of the full session; '/unshare' revokes it. '/export' writes the entire dialogue, metadata, and code changes to a .md file for offline reference.
Want to check code changes first
Press Shift+Tab in an OpenCode session to toggle between plan mode (AI proposes a step‑by‑step plan) and build mode (AI directly writes code). Approve or reject the plan before it runs.
Need a reusable workflow in your repo
OpenCode can pull skill definitions from the skills.sh marketplace. Installing a skill writes its scripts into an 'agents/skills' folder and makes the commands available via '/skillname'.
No agents.md in my repo
Running '/init' creates or updates an agents.md file based on your repository structure, embedding system prompts, folder maps, and rule definitions for the coding agent.
Want to try a new direction without losing work
The '/timeline' command lists all messages in the current context; selecting 'fork' on a message spawns a fresh session that inherits history up to that point, letting you explore alternatives without losing work.
Need advice from my own notes and contacts
By organizing notes, transcripts, and profiles in a folder hierarchy, you can ask OpenCode questions like 'who should be on my advisory board?' and it will synthesize answers using the indexed context.
▸How-to Everyone
Need a local AI coding assistant in your editor
You open a terminal in VS Code, download the installer from opencode.ai (bash script for macOS or npm command for Windows), ensure Node.js is installed, run the command to install OpenCode Terminal, then start it by typing 'opencode'. This sets up the local AI coding assistant.
Can’t pick a different code‑gen model or reasoning level
Inside an active OpenCode session you type '/models' to list available models, navigate with arrow keys, press Enter to select a model (e.g., DeepSeek V4 Flash), then optionally choose a reasoning level (Low‑Max). This lets you control quality vs speed/cost.
Need a development plan before coding
OpenCode provides two agents: 'Plan' to generate a development plan and 'Build' to write code. Switch between them with '/agents' or the Tab key. Planning first yields better results for complex features.
Need a fresh chat without old context
You can begin a fresh conversation with the AI by typing '/new' which clears context and starts a new session, useful for unrelated projects.
Want to add a paid AI model service
By running '/connect', you can attach API keys from paid providers like OpenCode Go, unlocking more powerful models. After selecting the provider, paste your API key to authenticate.
Have a screenshot of a UI change you want
You can drag‑and‑drop or paste a screenshot directly into OpenCode and describe the visual change (e.g., remove an icon). The model interprets the image and updates the code accordingly.
Made a code edit you don’t want
If a generated change is undesirable, typing '/undo' reverts the last instruction, while '/redo' reapplies it. This gives safe iteration over AI‑generated edits.
▸How-to Everyone
Need an AI assistant installed and logged in
Open Code is installed via a single terminal command that pulls the latest version and updates existing installations. After installation, running `open code login` lets you select an AI provider (e.g., OpenAI) and authorize with your personal API key, enabling global access to the agent.
▸How-to Everyone
Want your AI agent to browse and scrape sites
The MCP (Multi‑Channel Proxy) server lets Open Code control Chrome DevTools, giving the agent the ability to navigate webpages, click elements, and scrape data. Adding a JSON config file (`openode.json`) registers the server with the agent.
▸How-to Everyone
Need a list of qualified business contacts
By prompting Open Code with a natural‑language request, the agent uses the MCP server to browse search results, extract contact information, and write a markdown file. No manual scraping is required.
▸How-to Everyone
Downloads folder full of old and huge files
Open Code can query the filesystem, sort files by size or modification date, present a summary, and then execute deletion commands—all from a single prompt.
▸How-to Everyone
Too many startup ideas with no structure
Open Code can generate a Python script, install required libraries, run the script in an isolated virtual environment, and output a PNG graph that clusters ideas. The whole pipeline is orchestrated by the agent.
▸How-to Everyone
Too many sales calls get ignored
Using MCP and the `youtube-transcript-api`, Open Code can fetch video transcripts, parse them, synthesize insights, and produce a concise research brief—all without manual browsing.
▸How-to Everyone
My PC is running slow
Open Code can run system commands (e.g., `top`, `df -h`) to collect load averages, memory pressure, disk usage, and running processes, then compile the findings into a readable report.
▸How-to Everyone
I only have an article idea
By describing an article topic, Open Code can research sources, draft a markdown article, generate HTML/CSS, and launch a static site using any framework (React, Vite, etc.) automatically.
▸How-to Everyone
No documentation in your codebase
Open Code can scan a repository, detect undocumented functions or outdated READMEs, then write appropriate docstrings, markdown files, and update a `/docs` hierarchy without altering source code.
▸How-to Everyone
Need a ready investor deck
Open Code can take a concise business idea description, outline slide sections, generate content for each slide, design visuals, and assemble a Vite‑based web presentation ready for deployment.
Want a graphical AI workspace on your computer
Download the Open Code desktop application for your OS, run the installer, and open the app to see its three‑pane interface (projects, sessions, chat) with a prompt box at the bottom. This sets up the environment needed to use Open Code’s UI instead of CLI or IDE extensions.
Want to preview code edits before they run
Open Code offers two execution modes: Plan mode generates a step‑by‑step change plan, while Build mode applies those changes automatically. Switching lets you review proposed edits before committing them.
Need to pick a different LLM for generating code
The Model selector lets you choose any LLM from the Open Code Zen or external providers (Anthropic, Google, etc.). Changing models affects reasoning speed, cost, and output quality.
I want a to‑do list that saves my tasks
By prompting Open Code in Plan mode with “Create a simple to‑do web app with local storage”, the agent proposes files, asks styling preferences, then builds the app when you approve. This demonstrates end‑to‑end code generation from natural language.
Need a visual task board for my app
You can extend an already built project by prompting for new functionality (e.g., turn the to‑do list into a Kanban board). Open Code will plan file modifications and then implement them, showing how incremental development works.
Want to undo the last edit you made
Open Code tracks file edits and can undo them on request. Using a revert command in Plan mode shows the exact change that will be undone before applying it.
Want auto‑generated project docs
You can ask Open Code to create project documentation automatically. By prompting for an agents.md draft, it writes a markdown file with install/run instructions based on the repository contents.
Want to stop automatic file changes
The Settings panel lets you choose whether model‑requested actions require manual approval or are auto‑accepted. Setting permissions to default helps you see prompts for actions like file writes, enhancing safety.
Simple tasks need quick answers
Reasoning mode (Low‑Medium‑High‑Max) controls how much chain‑of‑thought the model uses. Lower settings speed up generation at the cost of depth, useful for simple tasks.
▸How-to Everyone
Need Open Code to work fast on Windows
Running Open Code inside WSL gives the best performance and terminal compatibility on Windows. The installer script pulls the binary, sets up paths, and makes the `opencode` command available in your Linux subsystem.
▸How-to Everyone
No consistent AI onboarding guide for our repo
The `agents.md` file acts as a living onboarding guide for the AI agent, telling it project structure, style rules, and safe actions. It prevents repeated prompting and keeps the agent’s behavior consistent across the team.
▸How-to Everyone
I want AI help without it changing code on its own
Plan mode restricts the agent’s permissions, prompting before any risky change, making it ideal for design, code review, and debugging. Build mode gives full tool access for actual implementation, refactoring, or fixing tests.
▸How-to Everyone
Need agents to repeat the same multi‑step process
Skills are markdown files that bundle knowledge, conventions, and multi‑step instructions. Once defined, an agent can load a skill to perform complex tasks (e.g., migrations, component scaffolding) without re‑explaining the process each time.
▸How-to Everyone
I keep typing the same prompt over and over
Commands are shortcut definitions that map a slash command to a specific prompt, model, and optional arguments. They act like buttons for frequent actions such as running tests or generating pages, reducing typing errors.
Want to talk instead of type in your agent session
By installing a one‑time skill from the Pipa tools page and invoking it in an OpenCode session, you enable a live huddle where you can speak to your agents and hear their responses. The skill creates a hosted audio channel and links it back into the OpenCode chat, streamlining planning without typing.
▸How-to Everyone
Need a single command to set up the editor on any OS
Running the provided curl command auto-detects your OS and installs the appropriate Open Code binary, simplifying setup across Mac, Linux, or Windows.
!Tip Everyone
Open Code — run multiple AI coding tasks in parallel
Open Code creates separate sessions per model, allowing you to start several coding jobs at once and receive independent completion alerts, eliminating the single‑terminal bottleneck.
▸How-to Everyone
Can't pick which AI model to use
Using the slash command `model` you can add any supported provider (Gemini, OpenAI, Anthropic, etc.) by entering its API key, enabling the platform to route tasks to the chosen model.
!Tip Everyone
Open Code — init command to generate agents.md
The `init` slash command scans your project files and creates an `agents.md` file with style guidelines, naming conventions, and error‑handling rules, reducing token usage for future runs.
!Tip Everyone
Open Code — review command to audit code quality
Running `/review` makes Open Code analyze your codebase for security issues, bugs, and style violations, then returns a report you can ask it to fix automatically.
!Tip Everyone
Open Code — add an MCP (Micro‑Component Provider) for token‑efficient docs
MCPs like Context 7 let Open Code fetch library documentation on demand at low cost; you enable them by editing the global `opencode.json` and adding a rule in `agents.md`.
!Tip Everyone
Open Code — create reusable skill for Xcode refactor patterns
Skills are saved instruction sets; defining a skill for common Xcode refactoring lets you trigger complex clean‑up with a single command, improving consistency and speed.
!Tip Everyone
Open Code — add custom command to commit and push git changes
By editing `commands` (via `/command`) you can map a short slash shortcut to a series of terminal actions, automating repetitive Git workflows directly from Open Code.
!Tip Everyone
Open Code Web — run the UI in a browser from any device
After installing the CLI, executing `open code web` launches a local server that serves the Open Code interface over HTTP, enabling access from phones or tablets on the same network.
!Tip Everyone
Open Code Mobile — access your Mac’s Open Code via Termius SSH
Enabling Remote Login on macOS and connecting with the Termius app lets you open a remote terminal on your phone; typing `open code` runs the full interface remotely, giving you mobile control of sessions.
▸How-to Everyone
Need a command‑line coding assistant you can launch instantly
Open Code can be installed with a single curl command from opencode.ai and started by typing 'opencode' in any terminal. This gives you immediate access to its agentic coding interface.
▸How-to Everyone
Want to try an AI without paying
Use the '/connect' command inside Open Code to select a provider (e.g., Open Code Zen) and paste an API key. Free models like BigPikko can be used without cost, enabling quick experimentation.
▸How-to Everyone
Want to add a ready‑made prompt bundle to your project
Skills are reusable prompt bundles stored in a .agents/skills folder. Installing a skill via its command adds detailed instructions that the agent can follow for specific tasks like front‑end design.
▸How-to Everyone
Need stricter rules for your AI’s answers
agents.md acts as a system prompt for the main agent; adding strict rules here controls its behavior (e.g., concise answers, use of sub‑agents). The file can be auto‑generated with '/init' or edited manually.
▸How-to Everyone
Need a headless browser for tests
MCP servers let Open Code control a headless browser (Playwright) to run end‑to‑end tests. Configuration is stored in opencode.json and activated with the '/mcps' command.
▸How-to Everyone
Need a helper that isn’t built‑in
Using 'opencode agent create' you can define a new specialized agent (e.g., coder) with its own description. This expands the toolset beyond built‑in bold and plan agents.
▸How-to Everyone
Need to keep your generated plan for later
Saving a generated plan into .agents/plans allows you to reload it later, clear the current context, and re‑execute tasks without losing work.
▸How-to Everyone
Need more detail or faster replies
The '/variants' command lets you choose low, medium, or high reasoning effort for the selected model, affecting response quality and token usage.
▸How-to Everyone
Need to run multiple commands simultaneously
By instructing the main agent to delegate work, Open Code spawns sub‑agents that execute independent commands and return summarized results, preserving the main context window.
▸How-to Everyone
Model streams partial JSON
Enabling streaming in the AI SDK causes the model to send partial JSON sections as they are generated, allowing UI components to appear incrementally.
The same set on /recipes, filtered by tool and role.
5Videos 4
OpenCode Full Tutorial: Free Models, Skills & MCPs
Demonstrates how to use OpenCode’s planning and building features, session forking, and second-brain queries
OpenCode Tutorial for Beginners: Setup, Agents, Skills & MCP
Shows how to set up an MCP browser server, stream structured AI SDK output, and build a custom sub‑agent with OpenCode
8 Insane OpenCode Use Cases! (just copy me)
Shows how to apply OpenCode to automate data analysis, documentation generation, and deep research tasks
Master OpenCode in 28 minutes
Shows how to use OpenCode to run parallel AI coding tasks, build reusable Xcode refactoring skills, and link AI providers via API keys
6FAQ 5
Is my spoken data sent to any external service?
No, the voice processing stays on your machine, so neither speech‑to‑text nor text‑to‑speech leaves your device.
How can I verify where the voice data is processed?
You can trace the end‑to‑end flow in your mind: the pipeline runs entirely on‑device, and you can map each step to see that no third‑party transmission occurs.
Do I have to pay for using opencode-voice?
The software itself is free and open source; the only cost is the compute resources (CPU/GPU) you already have available.
Can I run the voice plugin locally without internet?
Yes, you can clone the repository, install dependencies, and build it into a local `index.js` file that runs on your machine.
How do I get speech synthesis to work on CPU only?
Configure the plugin’s speak tool to point at Piper’s HTTP endpoint or local script; Piper provides a backend that runs entirely on the CPU.
7Glossary 10 terms
Show the 10 terms
opencode + voice
opencode-voice- The name of the tool that provides local speech‑to‑text and text‑to‑speech functionality.
index.js- A JavaScript file produced when you compile the plugin, which can be run by Node to activate the voice features.
Node packages- Software libraries installed with the npm command that the plugin needs to work.
Piper- An open‑source text‑to‑speech service that the plugin can call over HTTP to generate speech using only the CPU.
HTTP TTS API- A web interface that accepts text via an HTTP request and returns spoken audio, used by the plugin to produce speech.
plugin- A small add‑on you build and run locally to give opencode-voice its voice capabilities.
repository- The online folder (often on a platform like GitHub) that holds the source code you clone to build the plugin.
dependencies- External code packages required by the plugin, listed so they can be installed automatically.
compute- The processing power of your computer’s CPU or GPU that runs the voice software.
open-source repos- Publicly available code collections that anyone can view and modify, which provide parts of the voice layer.
8See also
💬 Discuss this chapter
Ask, share, or report — over on the Heidelberg AI community forum.