The lay of the land

Citations pinned at opencode@77429f5 (cloned 2026-07-08).

OpenCode bills itself as "The open source AI coding agent" from sst — an MIT-licensed TypeScript monorepo that runs on Bun (opencode/README.md:10). Its ~30 packages split UI from engine, and the split is the whole personality of the thing. The entrypoint is a yargs CLI (opencode/packages/opencode/src/index.ts:45-47) whose subcommands include serve (opencode/packages/opencode/src/index.ts:93): the harness itself is an HTTP server, and the TUI, desktop, and web apps are all clients that attach to it. Where Claude Code is one process that owns its own terminal, OpenCode is a server that owns the agent and lends its screen to whoever connects.

Internally, everything is an Effect service wired as layers — the prompt engine is declared Context.Service("@opencode/SessionPrompt") (opencode/packages/opencode/src/session/prompt.ts:111). Model I/O goes through the Vercel AI SDK's streamText (opencode/packages/opencode/src/session/llm.ts:280), and a code comment spells out the division of labor cleanly: "AI SDK owns provider execution and tool dispatch" (opencode/packages/opencode/src/session/llm.ts:276-277). OpenCode writes the policy — what tools exist, when to compact, who may approve — and rents the mechanics of streaming and tool-call matching from the SDK.

The loop

A user prompt is first persisted as a message row; then prompt() calls loop(), which runs the turn under a per-session run-state lock — loop hands the actual work to SessionRunState.ensureRunning, which keys a Runner per sessionID so a second concurrent call on the same session just awaits the in-flight run's outcome instead of starting a parallel one (opencode/packages/opencode/src/session/prompt.ts:1052-1071, opencode/packages/opencode/src/session/prompt.ts:1343-1347). The engine is a literal while (true) (opencode/packages/opencode/src/session/prompt.ts:1088), and its defining move is that it keeps no conversation in memory. Every single iteration re-reads the session's message history from the database, compaction-filtered, before deciding anything (opencode/packages/opencode/src/session/prompt.ts:1092-1094). The loop's state is the SQL store; control flow is derived from the data, not carried in local variables.

The exit test reads that freshly-loaded history: stop when the newest assistant message finished with a reason other than tool-calls, carries no unresolved tool parts, and is newer than the last user message (opencode/packages/opencode/src/session/prompt.ts:1111-1130). Otherwise the loop takes one "step": it writes a fresh assistant message row (opencode/packages/opencode/src/session/prompt.ts:1186-1201), assembles the tool set and system inputs, and hands an LLM stream to a processor handle (opencode/packages/opencode/src/session/prompt.ts:1272-1286). That SessionProcessor drains the AI-SDK event stream — text-delta, tool-call, tool-result, step-finish — into persisted message parts (opencode/packages/opencode/src/session/processor.ts:627-646) and returns one of three verdicts, "compact" | "stop" | "continue" (opencode/packages/opencode/src/session/processor.ts:30). The loop maps those to break, enqueue a compaction turn, or iterate again (opencode/packages/opencode/src/session/prompt.ts:1319-1329). Crucially, tool execution happens inside the stream — the AI SDK calls each tool's execute itself — so by the time the loop re-enters, results are already rows in the DB waiting to be re-read.

Tools and the gate

A tool is a Tool.Def: an id, a description (usually loaded from a sibling .txt), parameters as an Effect Schema, and execute(args, ctx) returning {title, metadata, output} (opencode/packages/opencode/src/tool/tool.ts:55-65). Tool.define wraps every tool with two universal behaviors: argument validation whose failure becomes a typed, model-facing error — "Please rewrite the input so it satisfies the expected schema" is fed back as the tool result (opencode/packages/opencode/src/tool/tool.ts:24-34) — and automatic output truncation with the overflow spilled to a file (opencode/packages/opencode/src/tool/tool.ts:130-145). The registry assembles the builtins (shell, read, glob, grep, edit, write, task, webfetch, todo, skill, patch…) (opencode/packages/opencode/src/tool/registry.ts:224-247), and SessionTools.resolve converts each Def into a Vercel AI SDK tool({description, inputSchema, execute}), wrapping the real call in tool.execute.before/tool.execute.after plugin hooks (opencode/packages/opencode/src/session/tools.ts:92-134). Dispatch is then entirely the SDK's.

The permission gate is where OpenCode diverges most sharply from Claude Code. Rules are a flat list {permission, pattern, action: allow|ask|deny} and evaluation is last-matching-rule-wins, defaulting to ask (opencode/packages/opencode/src/permission/index.ts:28-38). But the check is pull-based and lives inside each tool: instead of one central pre-execution gate, every tool calls ctx.ask() at the exact moment it knows what it is about to touch, carrying evidence. The edit tool asks with the concrete unified diff in its metadata (opencode/packages/opencode/src/tool/edit.ts:145-153); the shell tool parses the command into a syntax tree, walks every subcommand, and asks with per-command patterns (opencode/packages/opencode/src/tool/shell.ts:378-414). And because the harness is a server, Permission.ask cannot pop a prompt. When any pattern evaluates to ask, it parks the request in a pending map, publishes an Asked event, and blocks the tool's Effect fiber on a Deferred (opencode/packages/opencode/src/permission/index.ts:67-107). The reply arrives over HTTP from whatever client is attached — POST /permission/:requestID/reply calls svc.reply (opencode/packages/opencode/src/server/routes/instance/httpapi/handlers/permission.ts:16-38), which resolves the Deferred; a reject fails it (optionally carrying user feedback), while always appends allow-rules and auto-approves any pending request the new rules now cover, cascading across the session (opencode/packages/opencode/src/permission/index.ts:109-167).

Context and memory

Token accounting is folded from provider-reported usage on every step-finish event (opencode/packages/opencode/src/session/processor.ts:435-484). isOverflow compares the running total against usable — the model's input limit minus a reserved compaction buffer of 20k tokens (opencode/packages/opencode/src/session/overflow.ts:8-20, opencode/packages/opencode/src/session/overflow.ts:22-34). On overflow the processor cuts the stream short and returns "compact", and here is the twist: compaction does not summarize inline. compaction.create writes a synthetic user message carrying a compaction part into the session (opencode/packages/opencode/src/session/compaction.ts:513-536). The next loop iteration finds that queued task and runs it as an ordinary LLM turn — executed by a hidden built-in compaction agent with every tool denied ("*": "deny") (opencode/packages/opencode/src/agent/agent.ts:219-233). Compaction is just another turn the same loop dispatches, run by a locked-down internal agent.

After compaction, history-rewriting is a read-time filter: filterCompacted walks the messages, drops everything a completed summary covers, and retains only [compaction-user, summary, retained tail…] (opencode/packages/opencode/src/session/message-v2.ts:521-572) — and the loop applies it on every iteration (recall opencode/packages/opencode/src/session/prompt.ts:1092-1094). Two cheaper layers run alongside the summarizer: prune erases old completed tool outputs once they pile up, keeping the last turns (opencode/packages/opencode/src/session/compaction.ts:243-287), and every tool's output is already truncated at the source with the full text spilled to a file (opencode/packages/opencode/src/tool/tool.ts:130-145). There is no CLAUDE.md-style auto-loaded memory organ; the analogous instruction files enter as system-prompt inputs assembled per step (opencode/packages/opencode/src/session/prompt.ts:1257-1263).

对照 Claude Code

Same organs, rehoused in a client/server body. Each row maps OpenCode's mechanism to the Claude Code page that dissects the equivalent:

• The loop → /stories/loop/1/. Same "call model → run tools → loop until no tool calls" cycle, but Claude Code's in-memory message array becomes a SQL store re-read every iteration (opencode/packages/opencode/src/session/prompt.ts:1088), and the tool-execution half is delegated to the AI SDK inside one stream (opencode/packages/opencode/src/session/processor.ts:627-646).
• Tool anatomy → /stories/tools/1/. Same name + description-file + schema + execute shape (opencode/packages/opencode/src/tool/tool.ts:55-65), with a typed "rewrite your input" protocol on validation failure (opencode/packages/opencode/src/tool/tool.ts:24-34).
• The permission gate → /stories/tools/2/. Allow/ask/deny with an "always allow" memory, but inverted: the check happens inside the tool (which volunteers its own diff/command as evidence), and approval is an async HTTP round-trip through a server-side Deferred (opencode/packages/opencode/src/permission/index.ts:67-107) — where Claude Code's resolver is an in-process confirm queue by default, racing an optional remote/bridge channel alongside it (claude-code/src/hooks/toolPermission/handlers/interactiveHandler.ts:92).
• Compaction → /stories/context/1/. Threshold-triggered, model-written summary — implemented as a queued compaction turn run by a tool-denied internal agent (opencode/packages/opencode/src/agent/agent.ts:219-233), plus reversible output pruning Claude Code's page can contrast.
• Memory → /stories/context/2/. No dedicated auto-load organ; instruction files are system-prompt inputs (opencode/packages/opencode/src/session/prompt.ts:1257-1263) — "no such organ" is the finding.
• Sub-agents → /stories/multiagent/1/. The task tool spawns permission-scoped child agents (opencode/packages/opencode/src/tool/task.ts:43-62), but children are first-class persisted sessions with a parentID (opencode/packages/opencode/src/tool/task.ts:142-158), and the recursion guard is a default-deny task permission rule, not a code check (opencode/packages/opencode/src/agent/subagent-permissions.ts:14-27). Background tasks (the agent-background-tasks page, not yet built) report back by injecting synthetic user messages.
• Skills → /stories/caps/1/. A skill tool permission-gates loading a SKILL.md and returns its content (opencode/packages/opencode/src/tool/skill.ts:12-33).
• Hooks → /stories/caps/2/. Different organ in the same slot: no shell-command hooks — the extension point is an in-process JS/TS plugin system whose tool.execute.before/after functions fire via plugin.trigger (opencode/packages/opencode/src/plugin/index.ts:280-293).
• Plan mode → the cap-plan-mode page (not yet built). Plan mode is nothing but a ruleset: the built-in plan agent denies edit except for plan files (opencode/packages/opencode/src/agent/agent.ts:156-181).

What to steal

Three ideas OpenCode implements that are worth lifting:

1. The doom-loop breaker. The processor watches the last 3 parts of the current assistant message; if all three are tool calls with the same tool and byte-identical input, it forces a doom_loop permission ask — turning a silent infinite retry into a human checkpoint (opencode/packages/opencode/src/session/processor.ts:29, opencode/packages/opencode/src/session/processor.ts:353-380). Its default action is ask (opencode/packages/opencode/src/agent/agent.ts:119-136).

2. AST-scanned bash permissions with an arity dictionary. Rather than pattern-matching the raw command string, the shell tool parses the command into a tree, extracts every subcommand, and asks per subcommand (opencode/packages/opencode/src/tool/shell.ts:378-414); the generalized "always allow" pattern comes from an arity table that knows git checkout main should widen to git checkout * while touch foo widens to touch * (opencode/packages/opencode/src/permission/arity.ts:1-9). This is the principled version of the scratch cluster's CHAINING metacharacter guard.

3. Harness-as-server: the approval gate is an HTTP resource. Because the whole agent is a serve-able HTTP API (opencode/packages/opencode/src/index.ts:93), a pending permission is a server-side Deferred any client can list and reply to over REST (opencode/packages/opencode/src/permission/index.ts:67-107, opencode/packages/opencode/src/server/routes/instance/httpapi/handlers/permission.ts:16-38). That single decision is what makes multi-frontend and remote attachment fall out for free.

(Bonus, seen in the same source: the edit tool appends LSP diagnostics straight into its own output — "LSP errors detected in this file, please fix:" — so the model fixes type errors in the same turn (opencode/packages/opencode/src/tool/edit.ts:196-201).)