opencode
The client/server harness
Prerequisites
- Agentic Coding Basics
What You'll Learn
- Explain the client/server split and what it unlocks
- Use modes as a permission model
- Weigh provider-agnostic vs curated model strategies
Client/server, precisely
opencode runs as a client/server pair: the agent can run on one machine and be driven from another — including a phone.
The agent process: the loop, the tools, the model calls, and every session. It runs where your code runs — usually your workstation.
A thin view that sends input and renders output — the terminal UI is one client, a phone is another. Clients attach and detach; the agent does not notice.
Conversation and task state, held server-side. This is the piece most harnesses tie to a window — here, it outlives every window.
What the split buys you: long-running work that keeps going after you close the lid, sessions you can resume from a different device, and the ability to drive the agent on your workstation from wherever you happen to be.
Build vs plan: a permission model as modes
Two built-in agent modes toggle with Tab: build (full access) and plan (read-only) — a permission model expressed as modes.
| Action | plan (read-only) | build (full access) |
|---|---|---|
| Read files and search the repo | ✓ allowed | ✓ allowed |
| Answer questions, draft an approach | ✓ allowed | ✓ allowed |
| Edit or create files | ✗ blocked | ✓ allowed |
| Run commands that change state | ✗ blocked | ✓ allowed |
Reach for plan when
- You are in a repo you did not write
- You want the approach reviewed before anything changes
- The surface is risky — migrations, auth, infra
Reach for build when
- The plan already reads right
- You are in a tight loop against tests
- The change is scoped and mechanical
The point is not the two modes — it is that permissions are a first-class state you flip deliberately, instead of a per-action dialog you learn to click through.
Provider-agnostic vs curated
It is provider-agnostic across 75+ model providers with bring-your-own-key, alongside a curated shortlist.
The wide-open list gives you
- •No vendor lock: swap models without swapping your workflow
- •Price and latency shopping per task — cheap model for grunt work, frontier model for design
- •Local and self-hosted models when the code cannot leave the building
And it costs you
- •Quality variance: the harness is only as good as the model you socket in
- •You own the evaluation — nobody pre-tuned the prompts for your pick
- •Key management and billing across however many providers you touch
The curated shortlist is the hedge: start on a recommended model with sane defaults, and treat the long list as an escape hatch you exercise deliberately — when price, privacy, or a specific capability demands it. Contrast this with single-vendor harnesses, where the model is the product and swapping it is not on the menu.
Names change, slugs endure
opencode started life under SST and moved to the Anomaly org in 2026 — the product name stayed, the org did not (as of August 2026).
That rename is a live lesson in this fast-moving space: orgs, owners, and branding churn, while install paths and product slugs tend to hold. It is why this course keys every lesson on a permanent slug instead of an org name — and why your own bookmarks, docs, and scripts should too.
Install (MIT licensed)
curl -fsSL https://opencode.ai/install | bashPrimary sources
💡 Pro Tips
- 1.Default to plan mode in any repo you did not write. Read the proposed approach, then Tab up to build — the flip costs one keypress, a bad write costs a revert.
- 2.Project context lives in a generated AGENTS.md created by /init. Run
/initbefore your first real task, commit the result, and regenerate after big structural changes so every session — yours and your teammates' — starts oriented. - 3.Exploit the split for long tasks: kick off the work on your workstation's server, close the laptop, and check in later from another client. The session is where the server is.
- 4.Pick one model from the curated shortlist and stay on it until you have a feel for the harness — then use bring-your-own-key breadth to optimize price or privacy per task, one variable at a time.
Facts as of August 2026, verified against the project's repository and official docs.
The walkthrough, as text
-
1. The Server Behind the Prompt
opencode runs as a client/server pair: the agent can run on one machine and be driven from another — including a phone. The terminal you type into is just one client attached to that server — a thin view, not the agent itself.
-
2. Work That Survives the Window
Close the laptop and the task keeps running, because session state lives with the server, not the terminal window. Reattach from any client — your desk, another laptop, a phone — and pick up the same session mid-task.
-
3. Plan Mode Draws the Line
Two built-in agent modes toggle with Tab: build (full access) and plan (read-only) — a permission model expressed as modes. In plan mode the agent can read anything but change nothing — a hard boundary the harness enforces, not a suggestion in the prompt.
-
4. Tab Flips the Boundary
One keypress moves the permission line. The exact write that plan mode blocked now lands, because build mode grants full access. You choose the blast radius before the agent acts, not after.
-
5. Swap the Model, Keep the Loop
It is provider-agnostic across 75+ model providers with bring-your-own-key, alongside a curated shortlist. The harness loop stays the same either way — the model is a socket, not a weld.
-
6. Context by /init
Project context lives in a generated AGENTS.md created by /init. Run it once and the harness writes down what it learned about your repo — conventions, commands, structure — so every future session starts oriented.
Facts verified against the opencode repository and official docs, as of August 2026.
New lessons, straight to your inbox
5 more harness deep dives are on the roadmap. Subscribers read them first — free.
Check your inbox to confirm.