Skip to content

OpenCode: The client and the coding runtime

Understand OpenCode through its server API, configurable agents, permissions, skills and plugins.

Updated View as Markdown

OpenCode is a useful study of a coding product with a client/server architecture.1 The terminal interface is a client of the server, and the server exposes an OpenAPI contract that also supports SDK integration.2 This makes the runtime boundary an important part of the product, not an implementation detail that can be inferred from a terminal screenshot.

This study uses a pinned repository and documentation snapshot checked October 11, 2026. The screenshot is a captured public demo. The review scenario below is illustrative and was not run as a benchmark.

The visible interface is one layer

Figure 1 shows a request becoming search and file inspection. The captured agent asks for clarification when several candidate buttons are found. That makes the interaction visible without establishing the quality of a completed code change.

Pan on smaller screensOpen full size ↗

Figure 1. OpenCode terminal demo, reproduced from the repository under MIT. Model labels and counters belong to the captured demo; they are not current product defaults or benchmark results.3

What sits behind the client

Running the terminal application starts both a TUI and a server. A separately started server can expose the same API contract to another client. The architecture documentation includes session endpoints for creation, inspection, forking, interruption and summarization.2 Figure 2 maps those responsibilities.

System anatomyA client-facing API around a configurable coding runtime
ClientsPresentation can be separate from execution
  • Terminal UI

    Display conversations, tools and user input.

  • Other interfaces

    A client can interact with the server API.

  • SDK client

    Use the generated API contract from another application.

OpenCode serverOwn sessions and request routing
  • Session APIs

    Create, fork, inspect, summarize or abort a session.

  • Agent configuration

    Choose primary or delegated roles and their models.

  • Tool pipeline

    Apply configured permission decisions and plugin hooks.

Providers and workspaceKeep access and output explicit
  • Model provider

    A configured model supplies reasoning and tool requests.

  • Workspace tools

    Files, commands and configured external integrations.

  • Evidence

    Messages, tool results, changes and review.

Figure 2. Latent Light synthesis of the documented server, agent, permission and plugin boundaries.2456

The architectural opportunity is to change presentation without reimplementing the entire work loop. The tradeoff is a service boundary to operate: request state, streamed progress, authentication and access to the workspace need consistent ownership. A UI disconnect and a stopped agent are different events.

The server documentation provides optional HTTP basic authentication through configured credentials. Protecting that endpoint is separate from restricting what its tools can do on the server’s host.2 Moving a client does not move the workspace automatically.

Agent roles are configurations of work

The inspected documentation distinguishes primary agents from subagents. Build is the default primary coding role; Plan uses more restrictive tool permissions. Workers such as General, Explore and Scout address delegated tasks in child sessions.4

The exact permission behavior matters. A mode intended for planning is not a universal proof that no edits can happen. The documented Plan defaults ask for approval for edits and shell commands. A client or user decision can change what proceeds. Read the configured rules, not only the role’s name.

In a review task, the main role can retain requirements while a worker explores specific callers. The worker should return evidence and uncertainty. If it changes shared files, the coordinator still needs to reconcile those effects. This is a general design lesson, not a measured advantage of delegation.

Permissions use explicit rule resolution

OpenCode permissions can allow, ask or deny an operation. Granular rules match inputs such as commands or paths, with the last matching rule taking precedence. The inspected default is broadly permissive, with additional ask behavior for external directories and repeated identical calls, and read restrictions for certain environment files.5

That makes rule order consequential. A broad later allowance can change the meaning of an earlier restriction. Our suggested review is to test representative allowed and denied operations and inspect the effective result, especially when project and role configuration combine.

These are application policy controls. A process capable of running broad commands still needs appropriate host access and containment. Source availability makes the implementation inspectable; it does not itself certify isolation.

Plugins, skills and instructions form different layers

Plugins add executable behavior through lifecycle hooks, including events before and after tool execution. They can use application context and SDK access. Local modules and packaged plugins therefore belong in the host’s code-review and dependency policy.6

Skills provide on-demand instructions in SKILL.md directories. The documented discovery locations include OpenCode and compatible agent/Claude layouts, with permissions controlling which skills may load. Discovering the same file format does not establish identical semantics for every extension feature.7

AGENTS.md and configured instruction files supply project guidance. The rules documentation describes precedence and compatibility fallbacks. A team using several coding clients should inspect which guidance each actually loads; keeping two contradictory files creates ambiguity rather than portability.8

A task scenario: inspect before changing

Consider the screenshot’s general problem: a requested interface change has several possible targets. A useful workflow first identifies the intended screen and component. Clarification is justified when repository evidence cannot resolve the ambiguity; it should not become a substitute for inspecting files.

Once the target is clear, record the desired behavior, make the change, run appropriate checks and inspect the rendered interface. The API and transcript can expose the trajectory, but a completed tool call is not evidence that the visual result meets the request. These are original review criteria.

For an embedded client, preserve enough state to reconnect and inspect the session. Do not create a second task merely because a stream was interrupted. The same task also needs a permission contract suited to the server’s workspace, not just the client application’s notion of what the user clicked.

What to learn from the boundary

OpenCode makes the separation between client, session service and provider explicit. It is a useful design to study when an application needs more than one interface around a work loop. Configuration and plugins provide flexibility, while introducing policy, dependency and service-state responsibilities.

Compare the service boundary with Codex App Server, and the integration choices with Pi’s SDK and RPC. The comparison overview keeps these distinctions visible without treating every product as an interchangeable framework.

References

  1. OpenCode contributors. OpenCode repository, product surfaces and design. Snapshot checked October 11, 2026. ↩

  2. OpenCode contributors. Server documentation, client/server architecture, OpenAPI and session endpoints. Snapshot checked October 11, 2026. ↩ ↩2 ↩3 ↩4

  3. OpenCode contributors. Repository interface screenshot, reproduced under the repository MIT license. Captured demo, checked October 11, 2026. ↩

  4. OpenCode contributors. Agents, primary agents, workers and permission configuration. Snapshot checked October 11, 2026. ↩ ↩2

  5. OpenCode contributors. Permissions, allow/ask/deny, last-match precedence and defaults. Snapshot checked October 11, 2026. ↩ ↩2

  6. OpenCode contributors. Plugins, loading, hooks and tool events. Snapshot checked October 11, 2026. ↩ ↩2

  7. OpenCode contributors. Agent Skills, discovery, on-demand loading and skill permissions. Snapshot checked October 11, 2026. ↩

  8. OpenCode contributors. Rules, instruction-file discovery and compatibility. Snapshot checked October 11, 2026. ↩

Navigation

Type to search…

↑↓ navigate↵ selectEsc close