It is 1 a.m., and you are deep in a critical piece of code when the terminal throws up a cold “Quota Exceeded” or an API endpoint authentication error. The entire development rhythm stops dead. You already paid for a subscription, yet all you can do is stare at a cooldown timer.

This is the most absurd routine for AI-assisted developers in 2026: we pay for top-tier models, only to be locked inside vendor-specific CLI cages. The shell, the communication protocol, the model choice, and the billing model are welded together. If you want a cheaper or faster brain for the task at hand, you often have to run a local proxy just to translate between API formats.

OpenCode’s rise is a direct pushback against that kind of single-vendor capture.

1. The Essence of Compute Freedom: Decouple the Shell From the Brain

Most commercial AI coding tools follow a tightly integrated, closed-ecosystem path. The shell hard-codes the vendor’s protocol, and model choice revolves around the vendor’s own products. Swapping in a cheaper or more responsive model from another company usually means building a local proxy that translates one API format into another. That consumes memory and tends to break when tool calling gets complicated.

OpenCode flips the model. Think of it as an industrial-grade machine tool: the shell is responsible for reading local files, running shell commands, and managing context. Which brain sits inside is entirely up to the developer. Whether you want the price-performance of DeepSeek V4.1 Flash, the heavy reasoning of DeepSeek-V4-Pro, a high-intelligence Claude model, or an offline model running locally through Ollama, you switch between them through the same terminal interface.

The architectural advantage is just as practical. OpenCode v2 ships as a native binary and uses a client-server design: the TUI is only the front end, while a background service owns sessions, permissions, tool execution, and provider connections. Startup is fast, memory use is relatively low, and it does not behave like some Node.js-based CLIs that consume hundreds of megabytes before you type a single prompt. Even on an aging MacBook Pro, it stays responsive instead of spinning up the fans and slowing the whole system. The same background service can also serve terminal, desktop, and web clients, rather than spawning a heavyweight runtime for every window.

The model catalog comes from models.dev, and OpenCode surfaces available providers and models in the /models picker. There is no magic here: it separates the connection layer from the model capability layer. As long as a provider exposes an API, the same interface can orchestrate it. For engineers, that means optimization is back on the table. You can choose today’s brain based on task difficulty, latency, context length, and how much you are willing to spend.

2. A Friction-Free Install: Deployed and Connected in Three Minutes

Many older tutorials start beginners with editing environment variables in ~/.zshrc and hand-writing complex JSON configs. That is exactly how people get stuck when a variable is not loaded or a comma is misplaced. The most reliable path today is the official install script followed by interactive authentication.

1. Run the official installer

Open a macOS or Linux terminal and paste the official v2 install command. The script detects your system architecture and downloads the matching native binary:

curl -fsSL https://opencode.ai/v2/install | bash

After installation, reload your shell or open a new terminal tab and run opencode --version to confirm the version prints correctly. macOS users who prefer package management can install through Homebrew:

brew install anomalyco/tap/opencode-v2

If you already manage global tools in the Node ecosystem, npm is another option:

npm install -g @opencode/cli

The differences are minor. Pick the channel you already maintain:

MethodCommandBest for
Official scriptcurl -fsSL https://opencode.ai/v2/install | bashFastest setup with no extra package manager dependency
Homebrewbrew install anomalyco/tap/opencode-v2Long-term macOS use with brew upgrade
npmnpm install -g @opencode/cliExisting Node.js global toolchain and centralized management

Upgrade later with opencode upgrade. If you want to see which files would be removed before a clean uninstall, run opencode uninstall --dry-run, then opencode uninstall if you agree. It stops background services and removes the global cache, but leaves session data, configuration, and state untouched. Windows package managers are not supported at the moment; standalone binaries are available separately. This guide focuses on macOS and Linux.

2. Enter your project and launch the interface

Change into your project root and run opencode to open the terminal interface:

cd ~/code/my-project && opencode

You can also pass the project path directly:

opencode ~/code/my-project

If you only need a one-shot answer for a script or CI job without opening the interactive UI, use opencode run:

opencode run "Explain this repository"

For a lighter interactive mode, there is opencode mini. It keeps the conversation and tool calls but does not take over the whole screen, which is useful in a narrow terminal pane.

3. Write credentials directly with /connect (no environment variables required)

Once the interface opens, type /connect in the prompt and press Enter. Search for and select the provider you want to use, such as DeepSeek, OpenAI, Google, or OpenRouter, then paste your API key. If the provider supports OAuth, OpenCode will show an authorization link or device code and walk you through it.

OpenCode stores the key securely in its local credential store; in v2, that is the background service’s SQLite database. It does not depend on terminal environment variables, and it survives a restart. Run opencode auth list to see which accounts are connected, or opencode auth login to complete the same flow without opening the TUI.

There is one detail that trips people up: authentication and environment variables are not the same thing. If you really want to use a variable such as ANTHROPIC_API_KEY, it must be set in the environment of the background service that actually makes model requests, not merely exported in one terminal tab. For most individual developers, /connect plus auth list is enough and avoids the classic “I set it, why can’t it see it?” mystery.

4. Switch models and reuse your existing project rules

After authentication, type /models to switch between models with different prices and capabilities. You can also press Ctrl+X then M to open the model picker, or press F2 to cycle through recently used models. A practical cost-routing strategy is to use a low-cost Flash model for everyday edits and switch to a Pro reasoning model for multi-file refactoring.

To set a project default, create opencode.jsonc in the project root:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "provider/model"
}

Replace provider/model with the actual ID shown in /models. The config format supports JSONC, including comments and trailing commas. Changes normally reload automatically, so you do not need to restart for every edit.

If you already maintain project rules in another tool, such as GEMINI.md, the cleanest approach is to link it so OpenCode reads the same file:

ln -sf GEMINI.md AGENTS.md

OpenCode reads the global ~/.config/opencode/AGENTS.md and then project-level AGENTS.md files up the directory tree, combining them into persistent instructions. If you do not want to rename anything, add this to opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["GEMINI.md"]
}

Incidentally, in directories without an AGENTS.md, OpenCode falls back to CLAUDE.md. Developers migrating from Claude Code usually do not need to rewrite their entire development discipline. Keep your rules in plain text and the tool can be replaced. Lock your rules inside one vendor’s format and you are the one who gets locked in.

3. Your First Prompt: Turn the Terminal Into an Auditable Workbench

OpenCode is not just “ChatGPT stuffed into a terminal.” Its real value is connecting file reading, search, command execution, edits, and rollback into an auditable workflow. For your first session, start with read-only planning instead of asking it to rewrite everything at once.

Plan and Build: think first, act second

OpenCode v2 includes two primary agents:

  • Plan: explores and plans without editing normal project files. Use it to understand architecture, find risks, and break work into steps.
  • Build: the default coding agent. It can read and write files and run tools, so use it after the plan is clear.

Press Shift+Tab in the TUI to cycle agents (older versions may use Tab; check your installed version). The safest rhythm is: Plan produces assumptions and impact scope, Build makes one small change, then you inspect the diff and run tests immediately. That is far more reliable than dumping the whole repository on the model and asking it to “refactor everything.”

Common operations

ActionHowNotes
Attach a file@src/auth.tsType @ to search; add #20-45 for a line range
Run a shell command!npm testRuns in the current working directory; output stays in the session
Switch agentShift+TabCycles between Plan and Build
Model picker/models or Ctrl+X then MChanges the model for the current session
Command paletteCtrl+PLists every action available in the current view
Undo/undo or Ctrl+X then UReverts the latest message and its file changes
Redo/redo or Ctrl+X then RCancels the staged rollback
New sessionCtrl+X then NStarts with a clean context
Session listCtrl+X then LReturns to an earlier conversation
Compact contextCtrl+X then CUse when a long conversation approaches the context limit
Review changes/diffShows what the session changed

A few practical tips:

  • Attach files precisely with @; do not make “the whole project” your prompt. @src/auth.ts#120-180 is far more effective than “look at the login.”
  • Put test output back into the conversation with !. The model can see the real failure from npm test and fix the actual cause instead of guessing.
  • Run /diff after every change, then decide whether to /undo. OpenCode snapshots require a Git worktree to restore files. They are a convenience, not a backup or a transaction system. Commit important progress as usual.
  • Compact long conversations proactively with Ctrl+X then C. Context is not free. Rather than letting the model wander through stale information, compact and refocus.

A good opening prompt looks like this:

Do not edit any files yet. Read @README.md and @package.json, then explain the startup flow, the test commands, and the three modules most likely to break. Finish with the next step you recommend.

Once you confirm it understands the project, switch to Build:

@src/auth.ts#120-180 What happens in this block when the token expires? List three possible causes first, then propose the smallest fix without changing the public interface.

4. Four Practical Workflows: From Bug Fixes to Multi-File Refactors

1. Onboarding to an unfamiliar project: build a map before cutting

When you inherit someone else’s project, the most expensive cost is not writing code; it is not knowing where anything lives. Stay in Plan and ask OpenCode to read the README, package.json, route entry points, and tests. Have it produce a data-flow map: where requests enter, which modules they pass through, where state is stored, and how tests run.

This use case has almost no side effects, yet it saves hours of file browsing. Once the map matches your understanding, switch to Build and change what actually needs changing.

2. Fixing a bug precisely: hypothesize, verify, then edit

The biggest risk in bug fixing is a model that sounds confident but edits the wrong file. A safer process is:

  1. Attach the failing file and relevant tests with @.
  2. Ask for possible causes and which code each hypothesis needs to inspect.
  3. Use ! to run the reproduction command or tests so the result enters the conversation.
  4. After confirming the hypothesis, switch to Build and request the smallest fix.
  5. Review /diff and the test result again.

The benefit is that the model does not have to be right in one shot. It only has to stay inside a verifiable scope at each step, which raises the overall success rate substantially.

3. Multi-file refactoring: break a big job into reversible steps

Multi-file refactoring is where AI coding tools most often fail. Context gets long, the model forgets earlier constraints, and changing many files means it may update A while missing B. Break the work into a loop: plan → one file → test → next file.

  • Ask Plan to list affected files, call sites, and risks.
  • Let Build change one module at a time, running tests after each.
  • Use /diff to check whether it touched a public interface it should not have.
  • Commit each stable step so you have a real safety net beyond /undo.

This rhythm looks slower, but it is much faster than changing twenty files at once and then debugging the wreckage.

4. Put OpenCode into CI and everyday automation

The run subcommand is designed for scripts and CI. It does not open the TUI; it prints the model’s output back to the terminal:

opencode run --model anthropic/claude-sonnet-5-5 \
  "Review this repository for correctness and list the riskiest files."

In CI, pair it with --standalone so the run uses a private server, and put the provider key in that process’s environment:

- run: npm install --global @opencode/cli
- run: opencode run --standalone --model anthropic/claude-sonnet-5-5 "Review this pull request for regressions."
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

To integrate with other tools, --format json emits newline-delimited JSON, --file attaches files, and --continue resumes the previous session. Replace anthropic/claude-sonnet-5-5 with the model ID shown in your /models picker.

Cost routing: give each task the right brain

Task typeSuggested model tierWhy
Everyday edits, comments, testsLow-cost Flash-class modelFast, cheap, and low cost of failure
Multi-file refactors, architectureHigh-end reasoning modelNeeds longer context and better planning
Sensitive code, offline workLocal OllamaCode never leaves the machine; trade-off is speed and capability
High-volume CI checksExplicit model and budgetPrevents automation from quietly burning money

To see where the money actually goes, run opencode stats --days 7 --cost and opencode stats --models. Cost control is not about always choosing the cheapest model; it is about making the real cost of each task visible, then deciding whether an upgrade is worth it.

5. The Price of a Free Lunch and the Hidden Costs of Open Source

Open source and multi-model freedom are not free of trade-offs. Blind cheerleading only gets developers into trouble.

The boundaries of data privacy

OpenCode Console and some providers offer time-limited free models so beginners can try the tool without friction. But “free” usually comes with different data terms: the provider may retain conversations, use them to improve its service, or process code snippets under its own policy. For projects involving trade secrets, proprietary algorithms, or personal data, read the terms first, switch to a paid API key from your own account (if the provider offers a zero-retention policy), or connect a local Ollama model and work offline.

Also keep this distinction clear: a key stored locally does not mean your code stays local. As long as you select a cloud model, the contents of attached files go to that provider. True offline protection requires a local model plus controlled tool permissions.

The learning curve of complex agent tuning

Commercial closed-source tools such as Claude Code have deeply tuned prompts and tool-calling behavior for their own models. Their out-of-the-box “get it right the first time” rate is still somewhat better. OpenCode hands that tuning freedom back to the user. When you mix open models from different vendors, long contexts and complex cross-file edits demand more discipline: Plan/Build switching, permission rules, and tests.

That is not a flaw; it is a redistribution of responsibility. You gain freedom, and you take on the tuning work. For people willing to understand their tools, that is a good trade. For people who want one button that does everything, it may feel like a chore.

Operations, security, and version management

OpenCode is an actively evolving open-source project. Shortcuts, installation methods, and config formats can differ between v2 and older releases. When something goes wrong, run opencode service status to check the background service, then read the error in ~/.local/share/opencode/log/opencode.log. That is usually more effective than reinstalling blindly. Upgrade with opencode upgrade, and read the release notes before major upgrades so custom configs or agent behavior do not surprise you.

A few hard security rules:

  • Never put API keys in project files or commit them to Git.
  • Files exported by opencode auth export contain plaintext credentials. Treat them as secrets in transit and at rest.
  • Use permission rules to constrain high-risk commands. For example, require confirmation for git push in opencode.jsonc:
{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" }
  ]
}
  • Stay alert around .env, key files, and production configuration. OpenCode asks for confirmation before reading sensitive environment files by default, but the last line of defense is still your permission design and code review.

6. The Decision Map: When Should You Choose OpenCode?

Tools are not absolutely better or worse; they fit different situations.

SituationFitNotes
You code intensively every day and are tired of one subscription’s cooldownsHighMulti-provider switching is the core value
You want a cheap primary model plus a high-end backupHigh/models and stats --cost make cost visible
Your main development machine is oldHighNative binary and background-service architecture are relatively light
You need offline or high-privacy workHigh (with Ollama)Trade-off is model capability and speed
Your company already pays for a top-tier commercial subscriptionLow to mediumIf you do not want to manage APIs or model switching, a closed tool is simpler
You need one vendor’s deeply tuned first-try qualityMediumYou must supply prompts, permissions, and test discipline
You have strict compliance and centralized policy needsEvaluateConsole policies and managed config can help, but verify terms and deployment first

Choose it when: you code intensively every day and are tired of one subscription’s cooldown limits; you want to control cost dynamically with a cheap primary API (such as DeepSeek) plus a high-end backup; or your main machine is old and cannot handle a bloated Electron or Node.js tool running all day.

Do not choose it when: your company already pays for a top-tier commercial subscription, you do not want to manage API billing or model switching at all, and you just want one vendor’s turnkey experience. If you only write a few lines of code occasionally, a web chat interface may be faster; there is no need to go open source just for the label.

Eagle-Eye Conclusion

A mature engineering workflow never bets productivity on one vendor’s charity.

OpenCode’s value is not that it is “cheaper” or “smarter.” It is that it puts choice back in the engineer’s hands: models can change, providers can change, costs can be measured, and rules can travel with you. When one API raises prices, throttles throughput, or changes policy, you do not have to tear down your entire workflow.

Write your rules into plain-text AGENTS.md, hand execution to open, vendor-neutral OpenCode, and let tests and diffs be the final judge. When your tool shell is no longer captive to any AI giant, you have actually taken control of this compute revolution.


Official resources: OpenCode Docs | Install & CLI | Providers | Agents & Permissions | Troubleshooting

✦ Independent Journalism · Reader Support ✦

Support Independent Perspectives & In-Depth Insights

Every thoughtful analysis and candid critique comes from our dedication to truth and quality. We choose not to follow sensational algorithms or clickbait headlines.

Sustaining independent research requires reader support. Make a one-time or monthly contribution, securely processed by Google.

Payments secured by Google · Manage or cancel anytime in your Google Account