How a turn works
One claude process per conversation, and what the plugin does between the prompt and the reply.
A turn is one doStream call. There is one turn implementation: doGenerate is
doGenerateViaStream, which aggregates the same stream’s parts, so nothing below has a
second copy anywhere.
The prologue
Before the plugin asks the CLI for anything it resolves the spawn directory, probes the
claude version (the answer is cached per binary and gates every optional flag), reads
opencode’s MCP status and its tool registry, and plans the proxy tools for this turn.
That window is real time, and a stop pressed inside it used to be dropped, so the abort
watch (src/turn-abort.ts) is created before the prologue’s first await: a signal that
has already aborted never fires an addEventListener("abort") registered later.
The spawn
If the conversation has no live process, one is spawned:
claude --print --output-format stream-json --input-format stream-json --model <id> ...plus whatever this turn’s configuration adds: --mcp-config for the bridged servers and
the proxy endpoint, --append-system-prompt-file, --plugin-dir for staged skills,
--disallowedTools for everything proxied or closed, and --resume <session-id> when the
conversation already has one. If a process is already there it is reused and only the new
user message is written to its stdin.
Your message reaches Claude as written
A headless claude reads the last text block of each user message the way it reads typing:
a leading / runs one of its own commands and an @path attaches that file. Measured on
Claude Code 2.1.314, a message /model claude-sonnet-5-5 switched the running process to
Sonnet without a model call while opencode still showed the model it had picked, /cost
answered with Claude Code’s usage screen, and a message starting with a path such as
/etc/hosts is broken reached the model without the environment, deferred-tool, agent and
skill context of its turn (11,887 fewer prompt tokens).
So every user message the plugin writes carries client_composed: true, the field the Agent
SDK’s verbatimPrompts sets. The text then reaches Claude unchanged. Measured: hooks
(UserPromptSubmit context included), CLAUDE.md and the skill listing still arrive; the
only per-turn note that does not is the ultrathink keyword’s reminder, so use an effort
variant instead. An envelope answering a tool call is left as it was. /btw and
/claude-code-doctor are opencode commands the plugin answers before Claude Code sees
anything, so they are unaffected. Turn it off with verbatimPrompts: false. The interactive
transport types into Claude Code’s own input instead and is not covered.
Your own Claude Code commands and skills are the exception. A message that starts with
/name, where name is a command or skill you defined (in .claude/commands or
.claude/skills of the project or a folder above it, in your Claude config dir, or in a
Claude Code plugin you installed), goes out without the mark, so Claude Code runs it as you
typed it. Measured: with the mark, a command marked disable-model-invocation: true did not
run at all, and any other one ran only because the model chose to call its Skill tool,
three API calls instead of one. Built-ins such as /model and /cost keep the mark. The
plugin decides from the definition file itself, so your command runs as typed from the very
first message. It looks where Claude Code looks: your Claude config dir, and .claude from
the folder up to its git root (never the home dir’s .claude, which is the config dir’s
job, and nothing above it), with a nested command /ns:name at commands/ns/name.md. A
Claude Code plugin’s command lives in Claude Code’s plugin cache instead, so for it the
plugin goes by Claude Code’s own list: the commands a short background claude listed for
that folder when opencode started (see
Claude Code’s own commands in the / menu),
or, with claudeCommands: false, a claude in the same folder having listed it when it
started a turn. Every command that list names runs as typed from the first message.
A plugin skill’s short name is rewritten on the way. Headless Claude Code accepts a plugin
skill only under its full name: measured on 2.1.322, /test-cards answered “/test-cards is
not available in this session” while /stripe:test-cards ran the skill. So a message that
starts with /test-cards goes out as /stripe:test-cards when exactly one listed plugin
command ends in :test-cards and no command of your own, of the project or of Claude Code is
called test-cards; anything ambiguous or unknown goes out exactly as typed. Both opencode
majors pass a /name they have no command for through as an ordinary message (measured on
1.19.4 and 2.3.2), which is what makes a typed name work before the / menu lists it.
A command file named like a built-in (model.md)
replaces the built-in in Claude Code, so it runs too. Claude Code reads its commands when it
starts, so a command file you add while a conversation’s claude is running is not known to
it: the model answers that the command is not installed, and it runs from the next process
in that folder. A message that carries an attachment keeps the mark.
The stream
src/stream-parser.ts turns the CLI’s stream-json lines into AI SDK parts: text,
reasoning, tool calls and tool results, the result frame that ends the turn, and the CLI’s
own events (rate limits, compaction boundaries, MCP servers it skipped, hooks that failed).
src/turn-controller.ts holds what happens around that: the two watchdogs, late-result
delivery, the batched drain of proxied calls, both tool-call finishes and the auto-continue
nudge. The state they share is one TurnState object per turn (src/turn-state.ts), with
a comment on each field naming the invariant that owns it.
A proxied tool call leaves the stream as a tool-call part, opencode executes it, and the
result is handed back to the CLI’s held HTTP request. Nothing about that is on a clock: see
How a proxied call ends.
Sessions
Each chat keeps a long-lived claude subprocess so the model retains its native context across turns.
- Session key:
(cwd, model, tool-scope, opencode-session-id, provider, agent, spawn settings, effort), where the spawn settings are an agent’s prompt cache TTL,maxTurnsandmaxBudgetUsd, each only when set. Changing effort or a spawn setting ends the old process and resumes its Claude conversation in the new one, so one chat on one model and agent never runs two processes. A change of effort, spawn setting or model that lands mid-turn lets the old process finish that turn first and applies from the next one. The opencode session id comes from thex-session-affinityheader opencode sets on third-party provider calls. Two chats in the same project on the same model run in separate CLI processes, so they don’t race. In account mode, model IDs are suffixed per account, so account sessions do not collide. The opencode agent is in the key too, so one chat that moves between the plan and build agents runs on two processes: a Claude session answers under the system prompt of its first request, and the plan agent’s instructions must not follow the conversation into build. - Same chat, multiple turns → process reused, full Claude context retained.
- Same chat, back from another agent → the process is reused, and it is first told what was said while it was away. A build turn after a plan exchange used to send the build process only your newest message, so it carried on from its own last reply with no idea the plan existed. Now the messages between its last reply and your current one are replayed as text ahead of your message, under a
<missed_conversation>tag, on the same budget as a full replay; the log saysreplaying the messages this claude session missed. An ordinary turn, whose only new content is the process’s own reply, carries nothing extra. - Same chat, after an undo or an edit → the process is dropped and replaced by a copy of its Claude session cut at the last turn the thread still has. A
claudesession cannot have messages taken back out of its context, so after an/undo, an edited message or a regenerated reply the old process still held the turns you removed and would act on them. Every answered turn records where its reply ended in Claude’s transcript, and the next turn startsclaude --resume <id> --resume-session-at <that entry> --fork-session: a new session holding exactly the turns that are left, read from the prompt cache, with the old transcript untouched. The reply opens with a▌ **conversation rewound:**note and the log saysforking the claude session at the last turn the edited thread still has. When there is no such turn to cut at (the thread now ends on something another agent answered, an older Claude Code, the interactive transport, a transcript that is gone,forkOnRewind: false), the thread as it stands is replayed into a fresh session instead, and the log saysreplaying the conversation as text: the thread was edited or undonewith aforkRefusedtoken saying why. One shape is deliberately not recognised: an undo back to the very first message, or an edit of it, leaves nothing of the old thread in place, which is exactly what an opencode compaction looks like from here, and a compacted chat has to keep its process. - New chat forked from another (“Fork from here”,
/fork) → a copy of the parent’s Claude session cut at the turn the fork was taken from. opencode copies the history up to that message into a new chat, which arrives here as a new session key with nothing to resume, so it used to be replayed as text. When its history matches, reply for reply, a turn another chat on the same model and agent served in this opencode process, the first turn startsclaude --resume <parent> --resume-session-at <that turn's entry> --fork-sessioninstead: the same cut an undo takes, read from the prompt cache, with the parent’s transcript untouched. The log saysforking the claude session of the turn this conversation was forked from instead of replaying it. Those matches are kept in memory, so after an opencode restart only a fork of the whole conversation is continued: it starts from the parent’s saved session,claude --resume <parent> --fork-session, and the log saysforking the claude session of the conversation this one was forked from, saved before the restart. A fork from an earlier message after a restart replays. Anything else replays as before, and the replay NOTICE’sreasonsays why with afork-token (forkFromCheckpoint). - New chat → fresh process under the new session key.
- Resumed chat after restart → in-memory state is gone; a new process spawns and the conversation history is summarized and prepended. Each message in that replay is clipped from the middle, so the answer a message ends on survives: Claude Code runs its own tools without ending a step, so a reply’s tool calls and their output sit in the same message ahead of the prose, and keeping only the first 2,000 characters used to keep the tool output and drop the answer. The newest six messages keep 12,000 characters each, because what a follow-up points into is often two exchanges back, not only the newest reply; everything older keeps 2,000. The whole replay is capped at 180,000 characters, newest first, and says
[N earlier messages omitted ...]at the top when a long session needed it: without the cap a long session rebuilt a multi-megabyte first message that the API refused. Contributed in part by @bangnh1. - Abort (Esc / Ctrl+C) → the plugin sends the Claude CLI a stream-json
interruptcontrol request, so the CLI actually stops generating and running tools instead of finishing the abandoned turn on your bill. The process stays alive for the next message in that chat, and any proxied call the aborted turn left behind is released when that message arrives (see How a proxied call ends). If a turn is somehow still running when the next one starts, it is interrupted first (5 s cap). Contributed by @broskees. - Abort during the first moment of a turn → a turn spends a little time preparing before it asks the CLI for anything: resolving the spawn directory, probing the
claudeversion, reading opencode’s MCP status and tool registry. A stop pressed in that window used to be dropped, and the turn spawned, ran and billed anyway. It now ends the turn there: nothing is spawned, nothing is written, no running process is interrupted, and the reply is simply empty. - Idle timeout → when
idleProcessTimeoutMsis set, a completed headless turn arms an eviction timer (unset or0keeps workers until LRU eviction). Reuse cancels it, a worker found mid-turn when it fires is left alone and re-timed, and eviction preserves the session id, so the next message resumes the same conversation with--resume. An idleclaude --printholds around 250 MB, which is the reason to set it if you keep many chats open. - Cap: 16 active processes, LRU eviction. A process that is mid-turn is never the victim: eviction takes the oldest idle one, and when every process is busy it evicts nothing and warns instead, so a running answer is never truncated to make room.
- Deleted chat → deleting a session in opencode kills its
claudeworkers at once and forgets their session ids and per-chat state; there is nothing left to resume. Other chats, and the shared fallback bucket used when no session id is known, are untouched. - opencode exits → every retained worker is killed on the way out, so a hard shutdown does not leave
claudeprocesses reparented to init. - Crash → if the CLI dies mid-turn (no terminal
resultline), the turn ends with a visible error naming the exit code or signal and the last stderr the CLI wrote, not a silentstopthat reads as a short but finished answer. An abort you asked for is not reported this way.
Free and MIT-licensed, made by @khalilgharbaoui. If the plugin saves you time, you can buy its maintainer a coffee.
