OpenCode under the hood: one loop, many models, real environment feedback
How OpenCode combines a session loop, model-adaptive tools, permissions, and LSP diagnostics, plus the unique design choice that makes it resilient and a lesson for harness builders.
OpenCode presents itself as an open source AI coding agent, but architecturally it reads like a systems integration project: one harness that has to work across models, providers, interfaces, and real developer environments. Its answer is not to keep the loop clever and hope the model adapts. Instead, OpenCode normalizes differences inside the runtime and feeds environment signals back into the agent’s next decision.
That combination - stable internal loop, adaptive edges - is what makes it interesting to study.
A session-centric runtime
OpenCode is organized around sessions. The interactive surfaces (TUI, desktop, server/API workflows) sit on top of a core runtime that manages messages, tools, permissions, and model interaction. Rather than treating each prompt as an isolated request, the harness persists and processes a working session so multiple turns, tool calls, and interface modes can share the same state.
At the loop level, the design is intentionally direct: gather the current session context, resolve the right model and agent configuration, call the model, execute requested tools, persist results, and continue until the session reaches a natural stopping point. The simplicity of “run the loop” is balanced by careful work around it: task queues, compaction/overflow handling, and explicit state transitions.
Adapting to models instead of forcing one shape
One of OpenCode’s notable traits is that it does not assume every model should see the exact same tool interface. Tooling can be assembled per request based on provider/model/agent context. A well-known example from public architecture analyses is that some GPT-family setups use a patch-oriented editing flow, while other models get edit/write-style tools. The exact details evolve, but the principle is stable: the harness adapts its affordances to the model it is driving.
Provider variability goes deeper than tool names. OpenCode supports multiple execution paths for model interaction (including its default Vercel AI SDK-based path and an experimental native runtime path in recent versions), while aiming to converge on a consistent internal event stream for the rest of the system. This is a classic harness move: isolate external differences at the boundary, then let the core consume one normalized representation.
Permissions and execution are explicit
OpenCode treats tool execution as governed action, not just function dispatch. Permission rules can allow, ask, or deny actions, and those decisions are part of the runtime flow. That makes safety and user control a property of the harness, not a convention the model is expected to follow voluntarily.
The tool layer is also where OpenCode connects model intent to developer reality: reading files, editing code, running commands, integrating with external capabilities, and coordinating with subagents. Because these actions are mediated, the harness can inspect, gate, log, and transform them before and after execution.
The unique secret point: close the loop with real environment signals
The secret that stands out in OpenCode is this: it turns environment feedback into part of the agent’s reasoning loop.
A good example is diagnostics after edits. When the harness can apply a change and then surface language-server/compiler errors back as tool feedback, the model does not have to guess whether the edit was valid - it can react to concrete signals from the environment on the next turn. This is a big difference between “LLM that can write files” and “coding harness that collaborates with a development environment.”
Combined with session persistence and normalized event handling, this creates a tight feedback cycle: propose change, apply it under policy, observe real consequences, revise. The harness is not only transporting messages; it is actively shaping a loop where correctness signals are available.
Lesson for anyone building a harness
The transferable lesson from OpenCode is: normalize the outside, instrument the inside, and feed back reality.
Builders often focus on prompt quality or model choice, but harness reliability usually comes from plumbing:
- Normalize provider/model differences behind a stable internal interface so the core loop stays simple.
- Adapt capabilities to model strengths instead of pretending all models behave the same.
- Gate execution with explicit permissions and auditable decisions.
- Capture environment feedback (diagnostics, test results, command output, validation errors) and return it as structured input to the next step.
If the model is the brain, the harness is the nervous system. OpenCode’s strength is that it does not stop at sending commands outward - it brings the environment’s response back in, quickly and in a form the loop can use.
Sources
- OpenCode repository
- OpenCode documentation
- OpenCode agents docs
- OpenCode permissions docs
- Agent Harness Anatomy: OpenCode
- OpenCode session and LLM pipeline overview (Zread)
Weekly series
Read the posts in order:
- Adding a blog to my personal site (without starting over) - 2026-11-11
- Why PostHog is one of the first tools I add to a new product - 2026-11-18
- Anatomy of a coding harness: what makes AI coding agents work - 2026-11-11
- Context management in coding harnesses: what gets sent, and why it matters - 2026-11-18
- Goose under the hood: an MCP-native harness with a protocol at the center - 2026-11-11
- Pi under the hood: a minimal harness built around session trees and primitives - 2026-11-18
- OpenCode under the hood: one loop, many models, real environment feedback (this post) - 2026-11-11
- DeepSeek Harness under the hood: everything is a plugin, and the log is the contract - 2026-11-18
Previous: Pi under the hood: a minimal harness built around session trees and primitives Next: DeepSeek Harness under the hood: everything is a plugin, and the log is the contract