Need complete type hints for a bioinformatics codebase
A 6 000-line bioinformatics package gains full type coverage using only infrastructure the lab already controls; mypy catches a silent integer-vs-float bug on the first run.
Track 13 · Advanced
13.2.8
opencode
Open-source terminal agent — your key, any model, full control
1Overview
An open-source coding agent for your terminal, a desktop app, or an IDE extension — most people bring their own API key, though a rate-limited hosted plan exists for anyone who'd rather not manage one.
opencode is an open-source AI coding agent that runs in your terminal, as a desktop app, or as an IDE extension. Bring your own API key from any of 75+ supported providers — Anthropic, OpenAI, Google, Mistral, or a local model via Ollama — or connect an existing Copilot or ChatGPT subscription; you pay your provider directly, no markup. Two agent modes switch with Tab: 'build' executes code changes, 'plan' explores without modifying files. → BYOK means costs land directly on your API bill.
1.1Before you start
AI coding assistants— Reading AI coding assistants shows how OpenCode fits into collaborative, terminal-based code generation and debugging tools.A repo you can push to— First set up a GitHub account because it hosts code repositories, issues and actions where the open‑source terminal agent will operate.
1.2After this chapter you can
→Bring your own API key from any of 75+ supported model providers
→Switch between build mode (executes) and plan mode (explores) with Tab
→Run it in the terminal, a desktop app, or an IDE extension
1.3Best for
Full control over your model — 75+ supported providers, or reuse a GitHub Copilot / ChatGPT subscription you already pay for; no intermediate markup.
1.4Watch out
If you'd rather not manage an API key, the hosted alternative is rate-limited and limited to curated open-source models — not the full provider range BYOK gives you.
1.5Free vs paid
Core tool is free and MIT-licensed. A $10/mo 'Go' plan gives rate-limited access to curated open-source models without managing your own key.
2Sub-chapters
3In depth
opencode is an open-source terminal agent — your key, any model, full control. Below: what it's best at, and what to watch for.
4Lessons 5
4.1 Explain voice integration and privacy
A hands‑free way to drive opencode by voice, using a local speech‑to‑text engine and a text‑to‑speech tool that the agent can call back through its plugin system.
Describe how the voice layer works with opencode and its privacy implications
Try
No install yet — just trace the pipeline: mic → Whisper (your CPU) → opencode → speak tool → TTS (your machine) → speakers.Every arrow in that chain runs on hardware you own.
- Read the disclaimer that Nothing here is official to understand the community nature of the voice stack
- Identify that both the speech‑to‑text engine and the TTS component run on your machine, keeping spoken data local
- Check which LLM backend opencode is configured to use, noting that it may be remote
- You'll see A mental model of the pipeline without any terminal output
- Takeaway Voice processing can remain local while the LLM backend may be remote
- Check How does the voice integration keep spoken data local for privacy while still enabling OpenCode to handle your request, and which component of the pipeline might connect to a remote LLM backend?
- Cost Free — every piece is open-source. Compute cost is just your own CPU (listening) and optionally a GPU (voice cloning, covered in lesson 2).
4.2 Verify OpenCode does not store your code
OpenCode is an open‑source AI coding agent that claims to operate without storing any user code or context.
You will confirm that OpenCode runs locally and does not transmit project files to external servers.
- Install OpenCode using the install script:
curl -fsSL https://opencode.ai/install | bash. - Create a small test project with a single file containing identifiable text (e.g.,
echo "SECRET_TOKEN=12345" > token.txt). - Navigate to the project directory and start OpenCode with
opencode. - Run
/initto let OpenCode analyze the project, then ask it a question about the file usingHow is SECRET_TOKEN used in token.txt?.
- You'll see OpenCode replies with an explanation based solely on the local file content and no network activity indicator appears; no external request logs are shown.
- Takeaway Running OpenCode locally ensures that your code stays on your machine, satisfying privacy‑first requirements.
4.3 Ask Opencode questions by voice
A small CLI that captures microphone audio, transcribes it locally and forwards the text to OpenCode over HTTP.
Do this first Explain voice integration and privacy
Ask OpenCode a question using only your voice
Try
cargo install opencode-voiceThen open two terminals — one for opencode, one for opencode-voice.
cargo install, no GPU required — the local Whisper model runs fine on an ordinary laptop CPU, and no audio leaves your device. Credit: crates.io ↗- Start OpenCode listening on a port by running opencode --port 4096
- In another terminal launch the client with opencode‑voice --port 4096 --no-global
- Hold the space bar, speak your query, then release to send the transcription
- You'll see Your spoken question appears as text in the OpenCode terminal followed by its normal reply
- Takeaway The voice capture works entirely locally with a single HTTP bridge
- Check After holding space and speaking, how does opencode‑voice deliver your query to OpenCode and what do you see as confirmation?
- Cost Free and CPU-only — this half is realistically reproducible on any laptop, no GPU needed.
4.4 Add a spoken reply tool to opencode
A plugin that adds a speak tool to OpenCode, letting the agent send its reply to a local text‑to‑speech engine for audio playback.
Do this first Ask Opencode questions by voice
Add a spoken‑reply capability to OpenCode using a CPU‑friendly TTS engine
Try
git clone the opencode-voice-plugin repo, npm install && npm run build, then symlink it into your opencode plugin folder.Point its TTS backend at Piper (CPU) rather than dots.tts (GPU) unless you have a spare 10GB-VRAM GPU.
- Create a file named voice.js in your ~/.config/opencode/plugins directory containing the plugin’s JavaScript code
- Edit the plugin configuration to point at your local TTS HTTP endpoint
- Restart OpenCode so it loads the new speak tool
- You'll see The tool list now shows a speak command and asking OpenCode to speak plays audio through your speakers
- Takeaway The plugin system is permanent; you can swap any TTS engine behind the speak tool later
- Check What file do you place in the plugins folder to register the speak tool, and how does restarting OpenCode affect its availability?
- Cost Free and open-source throughout. Piper runs on CPU (realistic for any laptop); voice cloning via dots.tts needs a ~10GB-VRAM GPU, which most students won't have — treat that route as read-along, not hands-on.
4.5 Install OpenCode and initialize it in a project
OpenCode is an open‑source AI coding agent that runs in the terminal.
You will have OpenCode installed on your system and ready to analyze a local codebase.
- Open a terminal window and run
curl -fsSL https://opencode.ai/install | bashto download and execute the install script. - Verify the installation by running
opencode --version(or simplyopencode) and confirm it starts the TUI interface. - Navigate to an existing project directory with
cd /path/to/your/project. - Start OpenCode in that directory by typing
opencodeand press Enter. - In the OpenCode TUI, type
/initand press Enter to let OpenCode analyze the codebase and create anAGENTS.mdfile at the project root.
- You'll see The terminal shows OpenCode’s interface, then after
/inita message confirming analysis completion and anAGENTS.mdfile appears in the project folder. - Takeaway Installing and initializing OpenCode equips you with a local AI assistant that can understand and act on any codebase without external setup.
5You’ll know it worked 35 checkable outcomes in this chapter
- ✓mypy reports no errors or Any usage after running opencode
- ✓cleaned_data.csv is created with merged, deduped rows and missing numeric values filled
- ✓Running `opencode --list-tools` shows `speak` in the output and asking it to "speak" a reply plays audio through speakers
- ✓Opening the generated link shows the conversation; the exported .md file contains all prompts and responses
- ✓The forked session shows the selected past prompt as its first entry
- ✓The prompt shows a new session identifier or empty history
- ✓The UI shows “Plan” or “Build” selected and the model responds accordingly
- ✓The previously added confirmation dialog is removed from the app after reverting
35 outcomes in all — one per recipe below.
6FAQ, Tips & How-to 66
one problem, one solution, one action
Research & data tools2
Messy instrument CSV exports
Manual pre-processing of instrument exports is eliminated; the parser handles every file variant from the past three years without modification.
Internal tools & ops5
You don't need to know which file is broken — a plain description of the symptom is enough for opencode to trace it.
Naming the exact file and line lets opencode skip searching and go straight to a proposed patch.
Several CSV files with duplicate rows and gaps
One prompt covers merge, dedupe, and fill steps together, so opencode plans the whole pipeline rather than one command at a time.
Plan mode gives you a reviewable outline of the approach before opencode writes a single line of code.
Write unit tests while updating docs
Keeping each session's task narrow and independent avoids the two agents colliding on the same files.
Want local models usable in Alma
Link OpenCode to Alma so the agent can use local models
Model isn’t listed in the UI
Manually add a model name if it doesn't appear in the UI
Keep each prompt concise to stay within the context window
Need a roadmap for a huge project
Generate an implementation plan, then break it into phases for each session
Agent can’t open a headed browser or capture snapshots
Add a browser skill to let the agent open a headed browser and take snapshots
Want a full-screen terminal view of your current folder
Launching opencode from any directory opens a full-screen terminal UI that loads the current project
Turn a sentence into a working script
You can turn a plain English sentence into working code without leaving the terminal
Need to verify a generated script instantly
After approval, opencode runs the generated script and displays its output right in the terminal
Need code‑assistant AI without extra cost
You can log in with a GitHub Copilot or ChatGPT Plus/Pro account and let opencode use that subscription
Want the AI to make real file changes
Switching to build mode enables the agent to apply code edits based on the approved plan
Seeing the current mode in the bottom status bar prevents accidental edits
Agents stepping on each other's files
Assign each agent a distinct, non-overlapping subtask so they don't interfere with each other's files
Need to add unit tests
Demonstrates a concrete independent job for one agent
Want a parallel subtask for another agent
Shows a separate independent job for another agent
Terminal‑only agent feels limiting
You can launch the same opencode agent inside a native desktop application instead of the terminal
Need AI help while coding
You can invoke opencode directly from your code editor, keeping the workflow inside the IDE
No API key management
You can run models without managing your own API keys by using OpenCode Zen's hosted service
- **Free tier** — five models at $0 to start.
- **Pay-as-you-go** — paid models billed per 1M tokens.
- **Hosted** — no provider key of your own to manage.
Looking for free AI models to experiment with
You can experiment with opencode at zero cost using the free tier's five pre-selected models
Auto-reload guardrail
Your balance automatically replenishes when it falls low, preventing interruptions
Unsure about extra charge on credit‑card top‑ups
Every credit-card payment incurs a small additional charge, so factor it into budgeting
▸How-to Everyone
Understanding the full data path helps you verify where processing occurs and what stays on-device
External tools can’t feed data into the CLI
Running opencode on an explicit port lets external tools send it input via HTTP
▸How-to Everyone
Want to work on the plugin locally
Building the plugin locally compiles it into a runnable `index.js` file
My plugin won’t start with the app
Placing a symlink to the built `index.js` in the plugin folder registers the new tool on startup
▸How-to Everyone
Need CPU-only speech synthesis by pointing the speak tool at Piper
The plugin can be directed to any HTTP TTS API; configuring it for Piper enables CPU-only speech synthesis
After a restart, opencode lists the new `speak` tool, confirming successful installation
Need to undo your most recent edit
You can roll back the most recent modification made by Opencode
▸How-to Everyone
Need to install Opencode on Windows with a Linux shell
Run the same curl command inside WSL to install opencode on Windows
Terminal UI — a text‑based interface that runs in any terminal window
You get a mature, fully functional command-line interface for Opencode
What is opencode?
Opencode is an open-source AI coding agent you run on your own computer. It works in your terminal, as a desktop app (macOS, Windows, Linux), or as an IDE extension, and it can read your project's files, write or edit code, and run shell commands on your behalf — all under your control.
What is the optional paid subscription, and do I need it?
Opencode offers an optional low-cost subscription run by the opencode team that gives ready-to-use access to a curated set of open-source models without setting up separate provider accounts. If you already have API keys from providers you like, you don't need it — it's simply a convenience for users who want a single subscription instead of managing multiple API accounts.
Which AI models and providers does opencode work with?
Opencode works with many AI providers, including Anthropic (Claude), OpenAI (GPT), Google (Gemini), DeepSeek, Groq, and local models running on Ollama or LM Studio. If a provider offers an OpenAI-compatible API, opencode can connect to it. You choose the model; opencode is just the interface.
Can I use opencode fully offline with local models?
Yes. If you connect opencode to Ollama or LM Studio running on your own machine, no code ever leaves your computer. A reasonably capable local model that supports tool calling is recommended. This is useful when working with sensitive or private data.
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.
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.
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.
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.
The same set on /recipes, filtered by tool and role.
7Videos 3
OpenCode Tutorial for Beginners: Setup, Agents, Skills & MCP
Best 'all four pillars' intro. If you already use Claude Code with Leon's videos, the mental model transfers — same teacher, parallel tool.
Claude Code vs Cursor vs OpenCode: The FREE One Won? (2026 Honest Review)
The deciding-which-one video. If you're already a Claude Code user wondering whether opencode is worth the switch, this gives you a real answer.
Why OpenCode Is Better Than Claude Code (It's Free!)
The opinionated counterweight to the comparative review above. Honest about why a free terminal agent might fit your usage pattern better.
8FAQ 4
What is opencode?
Opencode is an open-source AI coding agent you run on your own computer. It works in your terminal, as a desktop app (macOS, Windows, Linux), or as an IDE extension, and it can read your project's files, write or edit code, and run shell commands on your behalf — all under your control.
What is the optional paid subscription, and do I need it?
Opencode offers an optional low-cost subscription run by the opencode team that gives ready-to-use access to a curated set of open-source models without setting up separate provider accounts. If you already have API keys from providers you like, you don't need it — it's simply a convenience for users who want a single subscription instead of managing multiple API accounts.
Which AI models and providers does opencode work with?
Opencode works with many AI providers, including Anthropic (Claude), OpenAI (GPT), Google (Gemini), DeepSeek, Groq, and local models running on Ollama or LM Studio. If a provider offers an OpenAI-compatible API, opencode can connect to it. You choose the model; opencode is just the interface.
Can I use opencode fully offline with local models?
Yes. If you connect opencode to Ollama or LM Studio running on your own machine, no code ever leaves your computer. A reasonably capable local model that supports tool calling is recommended. This is useful when working with sensitive or private data.
9Glossary 27 terms
Show the 27 terms
opencode
opencode- An open-source AI coding agent that runs in your terminal (or as a desktop app or IDE extension) and helps you read, write, and change code by chatting with a large language model.
TUI- Terminal User Interface — the interactive chat screen you see when you launch opencode in your terminal, where you type messages and watch the AI respond.
Plan mode- A built-in primary agent (switched to with the Tab key) where opencode is restricted from making file changes, so it analyses and describes how it would approach a task without touching your code.
Build mode- The default primary agent where opencode has full permission to read, write, and edit files in your project.
AGENTS.md- A plain-text file you place in your project folder (or home config folder) that gives the AI standing instructions about your project's structure, coding conventions, and quirks.
opencode.json- The main configuration file for opencode where you set your preferred model, provider API keys, tool permissions, and other project-level settings.
provider- A company that supplies the AI model opencode talks to (for example Anthropic, OpenAI, or Google); you configure your API key for each provider you want to use.
model- The specific AI brain opencode uses to answer your questions and write code (for example claude-sonnet-4-5 or gpt-4o); you can switch models mid-session.
OpenCode Zen- A paid AI model gateway maintained by the opencode team that offers a curated set of tested and verified models on a pay-as-you-go basis, so you can access quality-checked models without setting up separate provider accounts.
agent- A named AI assistant profile in opencode with its own set of instructions, permitted tools, and optionally a specific model — for example a 'Plan' agent that cannot edit files.
subagent- A specialist agent that a primary agent can invoke automatically to handle a subtask (like researching external docs); you can also invoke one manually by typing @agentname in your message.
skill- A reusable instruction set stored in a SKILL.md file that agents can load on demand, like a reference manual the AI can consult for a specific topic or workflow.
MCP server- An external tool server that connects to opencode via the Model Context Protocol, giving the AI access to additional capabilities such as searching documentation or querying a database.
snapshot- A save-point opencode automatically tracks as the AI makes file changes, used by the undo system to restore your code if you want to reverse the AI's edits.
session- One continuous conversation with opencode, including all your messages, the AI's replies, and any file changes made during that exchange.
permission- A setting that controls whether opencode can use a particular tool automatically (allow), must ask you first (ask), or is blocked from using it entirely (deny).
/init- A slash command that scans your project and automatically generates an AGENTS.md file with a summary of the codebase structure and build instructions.
/undo- A slash command that removes your last message, the AI's response, and any file changes made during that exchange, letting you rephrase and try again.
/redo- A slash command that re-applies a change you previously undid.
/share- A slash command that generates a shareable public web link to your current conversation so teammates can review the chat without needing opencode installed.
/compact- A slash command that summarises the current conversation to reduce context size, useful when a long session is making responses slower or less focused.
/new- A slash command that starts a fresh session, clearing the conversation history so you can begin a new task with a clean slate.
/models- A slash command that lists all AI models available to you through your configured providers.
/sessions- A slash command that shows your previous conversations so you can switch back to an earlier session and continue where you left off.
/thinking- A slash command that toggles the display of the model's reasoning blocks, letting you see the thinking the AI showed before answering — it controls visibility only, not whether the model reasons.
LSP- Language Server Protocol — a standard opencode uses to connect to language servers and receive diagnostics (errors, warnings) as feedback that helps the AI detect and fix code issues.
compaction- The process of automatically summarising older parts of a conversation to keep the context window from filling up, helping the AI remain accurate on long tasks.
10See also
💬 Discuss this chapter
Ask, share, or report — over on the Heidelberg AI community forum.