> ## Content Index
> Fetch the complete content index at: https://wuu73.org/aiguide-ghost/llms.txt
> Use this file to discover other available public pages before exploring further.

# OpenCode: The Client-Server Terminal Agent
- URL: https://wuu73.org/aiguide-ghost/coding-agents-opencode/
- Published: 2026-05-29T00:19:00.000Z
- Updated: 2026-05-29T00:19:00.000Z
- Description: Part of Agent Harness Field Guide.
- Author: WUU73
- Tags: Deep Dives, Agent Harness Field Guide, #Deep Dive Child, #Import 2026-09-12 06:38

Deep Dive • v1.14.40 • TypeScript/Bun • MIT • TUI/Web/Desktop • ACP + MCP

OpenCode is one of the clearest "post-Claude-Code" designs in this repo set: a provider-agnostic coding agent with a SolidJS terminal UI, a shared backend that can also power web and desktop clients, wildcard permission rules, worktree support, patch-based editing, a skill system, and real Agent Client Protocol collaboration instead of a single monolithic chat loop.

Shameless Plug[While we're deep-diving into complex CLI tools... let's be honest. Are you tired of feeling like nerds are trying to gatekeep the terminal life by having you memorize 30 key combos just to do basic stuff? Do you lie awake at night dreading the moment you have to edit a cryptic dotfile just to change a font size? Same. It's the AI age, we can have a crazy UI on top of the terminal with shameless amounts of AI built in to do things for you. We can even have AI nudge stalled coding agents for you when they stop for no reason.**ButtonsCLI**: The terminal for](https://buttonscli.com/?ref=wuu73.org)

(Alright, ad over. Back to the serious technical analysis.)

## What is OpenCode?

OpenCode is an open-source coding agent from Anomaly that positions itself as a provider-neutral alternative to Claude Code. The repo is organized around a shared backend runtime in `packages/opencode`, then fan-outs into three client surfaces: a **SolidJS + opentui terminal UI**, a **SolidJS web console**, and an **Electron desktop app**. There is also a TypeScript SDK and an optional server mode, which means the TUI is only one client of the runtime, not the runtime itself.

That architectural choice matters. Most coding agents in this directory are a single CLI persona with some attached tools. OpenCode is closer to an **agent platform with a terminal-first face**: permissions, sessions, tools, skills, ACP collaboration, worktrees, and provider routing are all runtime services.

| Layer           | Path                       | What it handles                                                  |
| --------------- | -------------------------- | ---------------------------------------------------------------- |
| Backend runtime | packages/opencode/src/     | Sessions, providers, permissions, tools, ACP, storage, worktrees |
| TUI             | packages/opencode/src/cli/ | SolidJS terminal interface via opentui                           |
| Web console     | packages/console/app/      | SolidJS browser client for the same runtime                      |
| Desktop         | packages/desktop/          | Electron shell with updater and native PTY plumbing              |
| SDK             | packages/sdk/js/           | Programmatic access to sessions, config, and runtime operations  |

## Built-In Agents and Collaboration

OpenCode ships with two user-facing built-in agents and one internal helper: **build** for normal coding work, **plan** for read-only analysis, and a **general** subagent that can be invoked for complex searches and multi-step tasks. The important part is not just that these agents exist, but that the repo already treats collaboration as a first-class runtime concern.

### Build Agent

Default full-access agent for development work. This is the normal coding persona: read, edit, shell, and project mutation are all available when permissions allow them.

### Plan Agent

Read-only analysis mode. It denies file edits by default and asks permission before bash. That makes it closer to an exploration specialist than a second full-power assistant.

### General Subagent

Internal helper for larger searches and multi-step tasks. OpenCode also implements **Agent Client Protocol**, so delegation is not just prompt fiction; it has a concrete session model.

🔌

#### ACP is real architecture here

The ACP implementation under `packages/opencode/src/acp/` supports session initialization, session forking, mode switching, prompt requests, permission requests, and usage updates. That makes OpenCode one of the few agents here where "subagent" behavior is backed by a transport protocol, not just a task tool and a prompt template.

## Tool System and File Editing

OpenCode's tool surface feels like a hybrid of Claude-style product tools and simpler edit/search primitives. The two most important editing paths are `apply_patch` and `edit`.

### `apply_patch` — the heavyweight path

Uses a custom patch envelope with `Add File`, `Update File`, `Delete File`, and `Move to` operations. It is BOM-aware, validates patch hunks, formats files after write when possible, and emits file watcher and bus events after mutation.

This is the path that makes OpenCode feel closest to Codex or Claude Code: file edits are treated as an explicit artifact, not just a string replacement.

### `edit` — the fast exact-match path

Uses exact string replacement, optional `replaceAll`, line-ending preservation, and semaphore-style per-file locking. It is smaller and more pragmatic than the patch tool, but still integrated with permission checks and file change events.

The interesting design choice is that OpenCode keeps both tools. It does not force every edit through one abstraction.

| Tool family  | What stands out                                                   | Why it matters                                                   |
| ------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------- |
| apply\_patch | Custom patch parser, move support, BOM awareness, formatting hook | Closer to version-control semantics than plain replace-in-file   |
| edit         | Exact replacement with file locks and line-ending preservation    | Fast path for smaller edits without full diff machinery          |
| shell        | Shell-family detection, metadata capture, process cleanup         | Command execution is runtime-aware, not a dumb spawn wrapper     |
| lsp          | Built-in LSP integration alongside AI tools                       | Rare among these agents; gives OpenCode a more IDE-like backbone |

## Permissions, Security, and Sandboxing

OpenCode has a real permission system, but it is not a sandbox. The repo is explicit about that tradeoff. Permissions are modeled as **wildcard rules with three actions**: `allow`, `deny`, and `ask`. Replies from the user or client are `once`, `always`, or `reject`.

### Wildcard permission rules

Rules can target permission names and path or command patterns. OpenCode evaluates them against both project config and stored approvals, then emits permission events over the runtime bus.

### Client-visible approvals

ACP clients can render permission prompts and reply with structured outcomes. This is important if the TUI is not the only frontend.

### No true isolation

Like Pi Mono, OpenCode does not claim to be a hardened sandbox. Its protection story is runtime permissions, not OS-level confinement. If you want stronger isolation, you still need containerization or other external controls.

The shell tool itself is more polished than many TypeScript peers: it detects shell families, captures metadata, handles Windows cleanup paths, and integrates with permission events. The repo also includes tree-sitter parsers for Bash and PowerShell, which signals a willingness to reason structurally about shell behavior instead of treating every command as an opaque blob.

## Providers and Model Strategy

OpenCode is aggressively **provider-agnostic**. The dependency graph in `packages/opencode/package.json` pulls in the Vercel AI SDK plus a very broad provider set: Anthropic, OpenAI, Azure, Google, Vertex, Bedrock, Groq, Mistral, Cohere, Cerebras, OpenRouter, TogetherAI, Alibaba, GitLab auth, Cloudflare-adjacent gateways, and more.

This is not just "we support many APIs" marketing. It fits the product thesis from the README: OpenCode wants to avoid coupling the agent identity to one model vendor. That puts it closer to Mux, Qwen Code, and Pi Mono than to Claude Code.

🧠

#### The interesting split

Claude Code is a polished product with a model-native identity. OpenCode is a polished runtime with a client-server identity. Its strongest differentiator is not a single model family; it is the runtime architecture that lets different clients and providers plug into the same core.

## Sessions, Skills, Worktrees, and UX

OpenCode's persistence layer is SQLite-backed and richer than a plain message log. Session tables track messages, parts, permissions, todos, and stored file diffs, which enables snapshots and reverts. Combined with worktrees and skills, it makes the runtime feel unusually stateful.

| Capability      | What OpenCode does                                                                      | Why it stands out                                                  |
| --------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Sessions        | Stores structured message history, tool parts, todo state, and diff artifacts in SQLite | More replayable and revert-friendly than plain JSON logs           |
| Skills          | Discovers SKILL.md assets from local and remote sources                                 | Closer to a reusable capability ecosystem than static prompt files |
| Worktrees       | Supports isolated git worktree flows                                                    | Important for parallel agent work and review-safe experimentation  |
| LSP             | Ships explicit config and tool support for LSP services                                 | Very few coding CLIs here make language servers first-class        |
| TUI/Web/Desktop | One backend, multiple clients                                                           | Rare in this category; most tools stop at one terminal interface   |

## Strengths and Tradeoffs

### Strengths

- **Client-server runtime**: one backend powering terminal, browser, desktop, and SDK access
- **Provider breadth**: unusually broad multi-provider support with no single-vendor lock-in
- **ACP collaboration**: real protocol-backed session delegation and permissions
- **Dual edit strategy**: patch-based editing plus exact replacement, both wired into permission and file-watch systems
- **LSP + worktrees + skills**: a strong combination for serious coding workflows

### Tradeoffs

- **No true sandbox**: permissions are a UX and runtime policy layer, not OS isolation
- **Large moving surface**: backend, TUI, web, desktop, SDK, and protocol layers make it harder to read than minimalist CLIs
- **Less singular identity**: compared with Claude Code or Crush, the product feels more runtime-centric than persona-centric
- **More infrastructure to reason about**: storage, bus events, worktrees, and protocol glue add power but also complexity

## Key Files to Read

| Area             | Path                                       | Why read it                                                                 |
| ---------------- | ------------------------------------------ | --------------------------------------------------------------------------- |
| Repo entry point | README.md                                  | Best overview of the client-server, provider-neutral product thesis         |
| Package surface  | packages/opencode/package.json             | Version, provider stack, SDKs, MCP/ACP dependencies, runtime shape          |
| Permissions      | packages/opencode/src/permission/index.ts  | Wildcard rule engine, allow/deny/ask actions, approval lifecycle            |
| Patch editing    | packages/opencode/src/tool/apply\_patch.ts | Custom patch parsing, BOM handling, formatting hook, bus events             |
| ACP              | packages/opencode/src/acp/agent.ts         | Session management, permission requests, usage updates, collaboration model |
| Worktrees        | packages/opencode/src/worktree/            | How parallel git contexts are treated as runtime state                      |
| Skills           | packages/opencode/src/skill/               | Discovery and loading of reusable capability bundles                        |
| TUI              | packages/opencode/src/cli/                 | SolidJS + opentui terminal layer                                            |

## Final Verdict

### Who is OpenCode for?

OpenCode is for people who want a serious open-source coding agent but do not want their workflow tied to a single model vendor or a single frontend. It is especially interesting if you care about **terminal UX, remote or multi-client control, worktrees, skills, and protocol-backed collaboration**.

The tradeoff is that OpenCode reads more like a small platform than a tight minimalist CLI. If you want the shortest path from prompt to edit, Pi Mono is cleaner. If you want the most integrated single-vendor product runtime, Claude Code is more cohesive. If you want a flexible open-source runtime with a terminal-first interface and an unusually modern architecture, OpenCode is one of the strongest repos in this directory.