How does OpenCode differ from ClaudeCode?

ClaudeCode is a closed‑source CLI; OpenCode is fully open and supports any provider you can point it to, plus a local Ollama fallback.

Can I use GPT‑OSSS 20b with OpenCode?

Yes, add its OpenRouter endpoint to the config and switch via \model.

What is ACP and why is it useful?

ACP (Agent Communication Protocol) lets third‑party apps, like Marimo, send and receive messages from the LLM without writing custom connectors.

How do I increase context beyond 64 K?

Ollama only supports 64 K; for larger contexts, use OpenRouter or OpenCodeZen models that expose a higher limit.

Is there a sandbox for running untrusted code?

Use `uvx --sandbox` when launching Marimo; the ACP connection is then isolated.

Does the auto‑update respect my custom config?

Yes – the config file is unchanged; only the binary updates.

What if the provider’s API changes?

OpenCode watches the provider’s schema and updates the CLI accordingly; if incompatible, you’ll see a clear error message.

OpenCode: The Open-Source Terminal Tool That Lets You Switch LLM Providers Anytime

Table of Contents

TL;DR

I can run local Ollama models from the terminal and swap providers in a single command.
I can add Marimo notebooks to my workflow with a single ACP integration.
I can control context length and avoid 4 K errors by setting 64 K in Ollama.
I can manage provider configuration from a simple JSON file.
I can stay cost‑efficient when cloud prices spike by switching to an open‑source fallback.

Why This Matters

As a software engineer, I hit the same frustrations every time I add a new LLM to my stack: price hikes, locked‑in APIs, and clunky config files. OpenCode solves these by giving me an open‑source, terminal‑centric playground that speaks to any provider. Whether I want a cheap local Gemma 3.1b or a high‑capacity GPT‑OSSS in the cloud, I can switch on the fly without rewriting scripts.

Core Concepts

OpenCode is a command‑line interface that bundles several LLM providers behind a single, consistent API. Think of it as a Swiss Army knife: the blade is your local Ollama instance, the screwdriver is a cloud provider like OpenRouter, and the toolbox is OpenCodeZen – a collection of open‑source models you can drop in when costs rise. Its design principles are:

Provider agnostic – one tool, many back‑ends.
Open‑source fallback – if the paid APIs go up, I can fall back to a local model in seconds.
ACP‑powered integration – third‑party apps like Marimo can hook into OpenCode through a lightweight protocol.
Auto‑update – every time I launch the CLI, it checks for the latest binary.
Backslash commands – \model lists or switches the active model instantly.
Dual modes – plan for brainstorming, build for code generation.

Parameter	Use Case	Limitation
Context Length (KB)	64 K for Ollama, 32 K for cloud	4 K default may truncate long prompts
Hosting	Local (Ollama)	CPU/GPU constrained
Hosting	Cloud (OpenRouter, OpenCodeZen)	Network latency, subscription costs
Tool Capability	Ollama (tool‑calling models)	Some local models lack tool support

The table above shows why I pick each provider for different jobs. When I need a quick test run, I go local; when I need a larger model, I hit the cloud; when I need reliability, I stay with an open‑source fallback.

How to Apply It

Install OpenCode
```
curl -fsSL https://opencode.io/install.sh | sh
```
The installer pulls the latest binary, verifies the checksum, and puts opencode in $HOME/.local/bin.

Configure Providers Create a JSON file at ~/.config/OpenCode/OpenCode.json:

{
  "providers": {
    "ollama": {"base_url": "http://localhost:11434"},
    "openrouter": {"base_url": "https://openrouter.ai/api/v1"},
    "opencodezen": {"base_url": "https://opencodezen.ai/api/v1"}
  },
  "default_context": 65536
}

The base_url points to the local or cloud endpoint, and default_context sets the context length globally.

Set Context Length for Ollama Ollama defaults to 4 K, which often truncates longer prompts.
```
opencode config set ollama.context 65536
```
Ollama Documentation (2024) explains how the –context flag works.
List Available Models
```
opencode \model
```
The CLI prints the names of all models registered in your providers. For example: Gemma 3.1b, GPT‑OSSS 20b-cloud, Kimi K2.
Switch to a Local Model
```
opencode \model Gemma 3.1b
```
The command tells OpenCode to route all future prompts to that local instance.
Integrate Marimo Launch Marimo with ACP enabled:
```
marimo run --acp
```
In the notebook, add an OpenCode widget and point it to the same provider. The widget streams output in real time over WebSocket. Marimo Documentation (2024) details the ACP handshake.
Plan vs Build
```
opencode plan "Outline a feature for a CLI tool."
opencode build "Write a test‑driven implementation for the feature."
```
The plan mode lets the LLM brainstorm without committing to code; build sends the output straight to your repository.
Quick Model Switching Anytime a provider’s price spikes, just flip the model:
```
opencode \model OpenRouter:GPT‑OSSS 20b
```
The change is instantaneous – no downtime.
Troubleshooting If the agent stalls, run opencode logs. Look for “connection timeout” or “context length exceeded”. Check that the provider’s base_url is reachable and that your network allows outbound traffic on the required port.

Pitfalls & Edge Cases

The following list outlines common issues and how to address them. Use the backslash command to quickly switch models, and always verify that the provider’s endpoint is reachable.

Quick FAQ

How does OpenCode differ from ClaudeCode? ClaudeCode is a closed‑source CLI; OpenCode is fully open and supports any provider you can point it to, plus a local Ollama fallback.
Can I use GPT‑OSSS 20b with OpenCode? Yes, add its OpenRouter endpoint to the config and switch via \model.
What is ACP and why is it useful? ACP (Agent Communication Protocol) lets third‑party apps, like Marimo, send and receive messages from the LLM without writing custom connectors.
How do I increase context beyond 64 K? Ollama only supports 64 K; for larger contexts, use OpenRouter or OpenCodeZen models that expose a higher limit.
Is there a sandbox for running untrusted code? Use uvx –sandbox when launching Marimo; the ACP connection is then isolated.
Does the auto‑update respect my custom config? Yes – the config file is unchanged; only the binary updates.
What if the provider’s API changes? OpenCode watches the provider’s schema and updates the CLI accordingly; if incompatible, you’ll see a clear error message.

Conclusion

If you’re a developer who juggles multiple LLMs and needs a single, reliable terminal interface, OpenCode gives you that. Install once, configure a JSON file, and you’re ready to run local, cloud, or open‑source models with the same commands. Keep your context length in check, use the \model command for quick switching, and let the ACP integration bring Marimo into the flow. The only people who might avoid OpenCode are those who need strict compliance with regulated data handling or who cannot run a CLI; otherwise, it’s a practical, cost‑effective solution.

Glossary

OpenCode – an open‑source terminal tool that interfaces with multiple LLM providers.
Ollama – a lightweight LLM hosting solution that runs locally.
OpenRouter – a cloud LLM service that aggregates many providers.
OpenCodeZen – a curated collection of open‑source LLMs.
ACP – Agent Communication Protocol, a lightweight protocol for LLM integration.
LLM – Large Language Model.
Context Length – the amount of text (in bytes) the model can process at once.
Tool‑capable model – a model that can call external functions via a structured API.
Plan mode – LLM mode for brainstorming and outlining.
Build mode – LLM mode for generating executable code.