Skip to content

Options reference

Every provider option, its type, its default and what it changes.

The minimum config is just the plugin entry above. Everything below is optional override that goes in a provider.claude-code block.

{
"plugin": ["@khalilgharbaoui/opencode-claude-code-plugin"],
"provider": {
"claude-code": {
"options": {
"cliPath": "claude",
"proxyTools": ["Bash", "Edit", "Write", "WebFetch", "Task"],
"skipPermissions": true,
"permissionMode": "default",
"bridgeOpencodeMcp": true,
"strictMcpConfig": false,
"idleProcessTimeoutMs": 900000
}
}
}
}
Option Type Default Description
cliPath string "claude" Path to the claude executable (a binary, not a shell command with flags). opencode’s config hook seeds this with "claude", so under opencode this default always applies; CLAUDE_CLI_PATH is only consulted when createClaudeCode() is called directly and the option is absent. Account providers wrap it with a generated script; never point it at one of those yourself.
cliModelCatalog boolean true Register the models the way the installed claude describes them. Once per Claude Code version, a background probe asks the CLI which models it knows, the context window it runs each one in and the effort levels it accepts, and keeps the answer in $XDG_STATE_HOME/opencode-claude-code-plugin/cli-models.json. Context windows and reasoning variants then follow the CLI, and a model the CLI’s own picker offers that the plugin does not list yet is added (at an unknown, zero price). Prices and the (N×) labels stay the plugin’s, because the CLI carries none. The probe is free: each check is a short claude --bare process with no credential that is never sent a message, so it makes no API request. Startup never waits for it, so a new answer applies at once on opencode 2 and from the next start on opencode 1. false registers the built-in list as it ships and runs no probe. See Models.
accounts string[] – Optional. Most setups need no accounts at all: with this unset you get a single Claude Code provider, id claude-code (opencode 1.x shows the id as its name), on your normal ~/.claude login. Supply names only to run several Claude logins side by side; default stays implicit, so ["work", "personal"] gives you Claude Code (Default), Claude Code (Work) and Claude Code (Personal). See Multiple Claude Code accounts.
accountFailover "ask" | "auto" | "off" "off" "ask" makes a usage limit end the turn on a form listing the other configured accounts, and continue on the one you pick inside the same turn. "auto" makes the same switch without asking: the same request moves to the next eligible configured account (in accounts order, default first, same accountGroups group, each tried at most once), so the rest of the turn is billed to that account. Both only ever fire when more than one account is configured, and only on a failed turn with a usage limit or an account that cannot serve. The default, "off", ends the limited turn on one ▌ **usage limit:** line instead: which account, which window, when it resets in your own time zone, and which other account to pick a model from. See When an account runs out of usage, Account failover and Automatic failover.
accountGroups object – Off unless set. Which accounts may see each other’s conversations: a map from an account name in accounts to a group name, e.g. { "work": "work" }. Every account you do not name, default included, is in one implicit group, so unset (and an empty map) means every account behaves as one group and nothing changes. With it set, the plugin only moves a conversation between accounts in the same group: the by-hand switch, the switch form, the automatic switch, the override either sets, and crossAccountResume. A switch across groups sends the other account nothing at all, neither the Claude transcript nor a text replay of the thread, starts fresh with only your latest message, and says so in one ▌ **account group:** note naming both accounts. The conversation is left intact on the account it was on, so switching back continues it. The switch form offers only same-group accounts, and the automatic switch moves only to one. An account name that is not configured is ignored with a WARN. See Account groups.
cwd string see description Working directory for the spawned CLI. Resolved lazily per request, first match winning: this explicit value, then the opencode session’s own directory (so opencode serve and the web UI spawn in the right project even though one server handles many), then process.cwd() when it is a real directory, then the project directory captured at plugin init (this rescues macOS GUI launches, where process.cwd() is /), and finally process.cwd() regardless. Startup diagnostics reports which tier won. Session tier contributed by @galvani.
skipPermissions boolean true Pass --dangerously-skip-permissions to claude. It is still passed when proxyTools is set: proxied calls go through opencode’s permission system regardless, but unproxied CLI built-ins do not. The one case where the flag is dropped is permissionMode: "plan", because the CLI lets the skip flag override plan mode outright. See Plan mode.
permissionMode acceptEdits | auto | bypassPermissions | default | dontAsk | plan – Forwarded to headless claude --permission-mode. "plan" also suppresses --dangerously-skip-permissions (see the row above). Not version-gated, so check that your installed CLI accepts the value. The interactive transport forwards it too (except bypassPermissions), and there "plan" can be left: the TUI offers ExitPlanMode and its approval is yours.
permissionPreset "read-only" – A named permission posture, so you set one option instead of combining five and getting one wrong. Opt-in: unset is exactly today’s behaviour. "read-only" replaces skipPermissions, permissionMode, controlRequestBehavior and controlRequestToolBehaviors, and filters the write and command tools out of proxyTools. See Read-only mode.
defaultSubagentCacheTtl string – Prompt cache TTL (5m or 1h) for plugin-discovered mode: subagent agents whose own definition states no cacheTtl. Reaches the CLI as CLAUDE_CODE_PROMPT_CACHE_TTL. Unset means the CLI keeps choosing, which is 1 hour on a subscription. An unrecognised value warns and changes nothing. See The prompt cache an agent writes.
defaultSubagentMaxTurns number – --max-turns for plugin-discovered mode: subagent agents that declare no maxTurns of their own. Claude Code counts it per user message (API round trips), so a reused process is not used up by it; a message that hits it ends as error_max_turns. Needs CLI 2.1.280+; print-only, so the interactive transport does not apply it. See Budgets and caps.
defaultSubagentMaxBudgetUsd number – --max-budget-usd for plugin-discovered mode: subagent agents that declare no maxBudgetUsd. Claude Code counts it over the process’s whole life and restarts it on every --resume, which is why it applies to subagents only. Checked against claude --help; print-only. See Budgets and caps.
maxBudgetUsd number – Off unless set. A dollar cap on one opencode conversation: its own turns plus every subagent it started, summed from the CLI’s own total_cost_usd. Notes at budgetWarnAt; once the cap is spent the next message ends before anything is spawned, with one ▌ **budget:** note and an error finish (budget_exceeded). Compaction is exempt. In memory only, so an opencode restart starts it again; raising it needs a relaunch. See Budgets and caps.
budgetWarnAt number[] [50, 80] Percentages of maxBudgetUsd at which one ▌ **budget:** note is written, each once per conversation. [] keeps the stop and drops the notes. Ignored without maxBudgetUsd.
maxBackgroundSubagents number – Off unless set. How many background subagents may run at once. A background: true task, or a task_batch with background tasks, that would go over it is refused whole with a tool result naming the cap and the running count; foreground dispatch is never capped. See Budgets and caps.
leanGenerate boolean false Answer a detached generate call (opencode 2 experimental.generate.text: no opencode session, no agent, not compaction) with one lean claude -p on the requested model: no tools, no MCP servers, no slash commands, no setting sources (so no CLAUDE.md, user or project, and no hooks), no session file, in a fresh empty directory inside the plugin’s own scratch directory. The input goes in as a composed message, so an @path in it is never attached. OpenChamber uses this call for its AI session rename, its walkthroughs and its dictation clean-up; as a full turn the model answered the material instead of doing the job. Any failure, or 180 s without an answer, runs the normal turn, which shows the reason (a usage limit, an expired login) as it would anyway. Needs a Claude Code whose --help lists --tools, --setting-sources, --disable-slash-commands and --no-session-persistence (2.1.288 to 2.1.314 checked); an older one keeps the normal turn. On opencode 1.x the only call that matches is opencode agent create. It is a claude -p on either transport. See #170.
titleModel string – Off unless set. A Claude CLI model, for example "haiku", that names sessions. A title request then gets the same lean claude -p as leanGenerate on that model and on this provider’s account, with the title agent’s system prompt as instructions and the conversation’s last 12,000 characters, instead of the synthetic title (the first six non-stop words of your first message; on opencode 2 they are read from inside the <message> element of its title request, so its lead-in no longer becomes the title). One short call per title on the account’s own plan, about 3 seconds on Haiku. Any failure, or 30 s without an answer, keeps the synthetic title; a model Claude Code does not know is also warned about once. Needs the same Claude Code flags as leanGenerate. Unset, a title request starts nothing at all. See #169.
subagentDispatch "ask" / "off" "off" Off unless set. Ask, before a proxied task or task_batch dispatch reaches opencode, which model, reasoning effort and Claude account the subagents it is about to start should run on. With "ask" the dispatch is held and the turn ends on opencode’s own question form; the real task calls are released, with your answer applied, on the next step of the same opencode turn. Always one question first (Same as last time, Default, four curated model/effort combos, Customise…), so the common answer is one click. Customise… opens one row per agent type plus an account row; the account row can open one account row per agent type (Per type…) and a type row can open one row per task, both on the same third form. Every row takes a typed answer as well, including an @account token, which is how one task gets its own account. The account is choosable at three widths and the narrowest wins: dispatch, agent type, task. The answer reaches each child’s own claude spawn and beats forceModel, defaultSubagentModel and the inherited effort. Same as last time is kept per opencode session in $XDG_STATE_HOME/opencode-claude-code-plugin/subagent-dispatch.json, so it survives an opencode restart; a remembered model or account that is no longer available is dropped and said out loud. A dismissed form dispatches with the defaults and says so; the dispatch is never lost. Never on compaction, never inside a child session. See Choosing per dispatch, not per file.
subagentDispatchCrossGroup boolean false Let subagentDispatch’s account answers, offered and typed, and on opencode 2 a subagent model named in the conversation, reach accounts outside the dispatching account’s own accountGroups group. Off by default and never implied: a subagent is handed the task text the main agent writes, which can quote the conversation, and it reads the repository, so offering another group is offering that group the conversation by another route. Does nothing with accountGroups unset.
defaultSubagentModel string – Model that plugin-discovered mode: subagent agents run on when their own definition pins nothing. The caller’s account is kept; only the model name changes. An agent’s own forceModel wins over it, and an unknown id is refused rather than spawned. Unset means no implicit override at all. See Subagents: your account, their model.
fallbackModels string[] – Ordered models to try when the one a turn would run on is refused. The default for agents that declare no fallbackModels of their own; a per-agent list replaces this one rather than extending it. Always the same account, never a different one. Only two things arm it: the CLI refusing the model (model_not_found) and a usage limit on an account with no other account to offer. Each model is tried at most once per turn and an exhausted chain surfaces the original error. Unset means no chain at all. See Fallback model chain.
proxyTools string[] ["Bash", "Edit", "Write", "WebFetch", "Task"] Claude built-in tools to route through opencode’s executor + permission UI. Opt-in extras: "Question", "Compress". See Selective tool proxy.
extraDisallowedTools string[] – Extra Claude built-ins to switch off with --disallowedTools, on top of what proxyTools implies. Claude’s names, e.g. ["NotebookEdit"]. See Closing a tool with no proxy.
mapReadRules boolean true Carry opencode’s own read permission deny rules onto the Read the CLI runs itself. Only deny is carried, and opencode’s own *.env default is an ask, so a default install maps nothing. See What opencode’s own rules do not reach.
proxyToolTimeoutMs Record<string, number> – Optional wall-clock backstop per proxy tool, in ms, keyed by proxy tool name (bash, task, …). A call normally ends on an event the plugin listens for (result, abort, next message, process exit, chat deletion), not on a timer; see How a proxied call ends. Defaults: 10 min flat, task / task_batch → none, question → 30 min. 0 disables a tool’s deadline; negative or non-numeric values are ignored. For bash, the call’s own input.timeout is honoured on top (max(resolved, input.timeout)). See Per-tool proxy timeouts.
planModeQuestion boolean false Route ExitPlanMode approval through opencode’s native question tool instead of a text “(yes/no)” prompt. Opt-in. Unreachable on the default headless transport, which is not offered an ExitPlanMode tool at all; on the interactive transport it is how a plan is approved as a form. See Plan mode.
controlRequestBehavior allow | deny allow Default response when skipPermissions: false and Claude sends a can_use_tool control request.
controlRequestToolBehaviors Record<string, "allow" | "deny"> – Per-tool override for can_use_tool. Example: { "Bash": "deny", "Read": "allow" }.
controlRequestDenyMessage string built-in message Message returned to Claude on a deny.
bridgeOpencodeMcp boolean true Auto-translate your opencode mcp block into Claude’s --mcp-config. See MCP bridge.
bridgeMcpOauthTokens boolean false Give a bridged remote MCP server the OAuth bearer token opencode already holds for it, instead of letting the Claude CLI report it needs-auth all session. Off by default because it copies a credential out of opencode’s own store; opencode 1 only. See MCP bridge.
mcpConfig string | string[] – Extra --mcp-config paths/JSON passed alongside the bridged config.
strictMcpConfig boolean false Pass --strict-mcp-config so Claude loads only the configured servers and ignores ~/.claude/settings.json.
hotReloadMcp boolean true With MCP bridging on, compare the merged MCP config and runtime status at the start of each turn and respawn the claude process when they drifted, so a server you just enabled, disabled or finished connecting becomes visible without restarting opencode or opening a new chat. It only ever acts at a safe boundary: never during /compact, never while a proxied call is still in the air, a turn is still running or a plan-mode approval is outstanding, and the Claude session id is preserved for --resume so the conversation continues. A log line at INFO names which servers joined and left. A server that flaps buys at most one respawn per minute per conversation (CLAUDE_CODE_MCP_HOT_RELOAD_COOLDOWN_MS). Set false to keep a cached subprocess until the chat is reset. It does not reload other provider options and does not watch the contents of files named in mcpConfig.
mcpConnectWaitMs number 3000 How long the first turn of a conversation waits for MCP servers opencode reports as still connecting before planning the claude spawn without them. Only opencode 2 can report that state (pending); opencode 1’s own status call blocks until every server has decided, so this budget is what makes the two majors behave alike. Set 0 to always plan with whatever the host says at that instant. Aborting the turn also ends the wait at once. A server slower than the budget is not lost either way: it is still bridged, and hotReloadMcp moves the conversation onto a process that has it on the next turn.
proxyOpencodeMcpTools boolean false Route opencode’s MCP-backed tools through the in-process opencode_proxy server instead of bridging them straight into Claude’s --mcp-config, so each call executes once, inside opencode, with its permission prompt and its tool row. The default changed from true to false in this release, and no behaviour changed with it: at true it used to route nothing at all, because discovery read opencode’s tool registry, which contains built-ins and plugin-declared tools and has never contained an MCP tool. Discovery now reads the model tool set opencode passes the provider, which is where MCP tools actually are, so the option works, and turning it on is the operator’s decision rather than a silent migration of traffic that the direct bridge is handling today. Two caveats before enabling it: pair it with strictMcpConfig: true, because a server also registered in Claude Code’s own config is reached directly and bypasses the proxy entirely; and a routed call runs in opencode with the calling agent’s permissions, the same trade proxyOpencodeTools makes. Per server: one with a tool in the agent’s tool set is proxied; one opencode has connected but gave this agent none of its tools (an explore subagent, say) is left out of the spawn entirely; any other server keeps the direct bridge, and one INFO line names the withheld and the bridged ones (see MCP bridge). Do not treat this as an exactly-once guarantee for write-capable tools. With the option off, every enabled server is bridged into every spawn, subagents included.
proxyOpencodeTools string[] [] Forward explicitly named opencode tools through the proxy (for example, a plugin’s compress or V2 Code Mode execute). V1 uses registry ids; V2 uses the current model tool snapshot, including its real JSON Schema and agent visibility, not the registry’s empty schemas. A forwarded tool runs inside opencode with the calling agent’s permissions. A name already held by a proxy def is dropped with a warning. The read-only preset refuses execute. See Forwarding opencode’s own tools and V2 Code Mode.
stripContextReminders boolean false Remove opencode-dcp’s <dcp-system-reminder> blocks from message text when no compress tool is proxied, so an order the model cannot follow stops being re-sent with every message that carries it. Inert as soon as compress is reachable. See Trimming unsatisfiable context reminders.
alwaysLoadProxyTools boolean | string[] ["bash", "edit", "write"] Proxy tools Claude Code puts in every request instead of deferring them behind its ToolSearch tool, which saves the extra API request the first proxied call of a claude process otherwise costs. true loads every tool the proxy serves (the MCP tools proxyOpencodeMcpTools routes included), false defers them all, a list names proxy tools (case-insensitive). See Always-loaded proxy tools.
parallelWebfetch boolean true Run the proxied webfetch calls of one Claude reply at the same time, in one opencode step, instead of one step per fetch. The proxy marks webfetch read-only (the MCP readOnlyHint), so Claude Code sends the fetches together, and the plugin waits for the reply to finish (at most 2 s) before handing them to opencode. Also lets Claude fetch under permissionMode: "plan", as its own WebFetch can. false serves webfetch as before. See Parallel webfetch.
claudeCommands boolean true List Claude Code’s own commands and skills (yours, the project’s, every enabled Claude Code plugin’s) in opencode’s / menu, described as Claude Code: ..., and send a typed one the way Claude Code accepts it: /release goes out as /appical-core:release when exactly one enabled plugin defines release. The list comes from a short background claude that is sent initialize and never a message, with hooks off and no MCP servers, once per opencode start and folder (about a second, no API request), kept in $XDG_STATE_HOME/opencode-claude-code-plugin/claude-commands.json. Claude Code’s built-ins and names opencode already has are never added. The menu is read when opencode starts, so a skill installed while it runs is listed from the next start. false adds nothing, runs no probe and sends every message as typed. See Claude Code’s own commands in the / menu.
verbatimPrompts boolean true Deliver every message as written: Claude Code no longer runs a message starting with / as one of its own commands (/model claude-sonnet-5-5 used to switch the running process to Sonnet) and no longer attaches the file an @path names. Hooks, CLAUDE.md and the skill listing still arrive; the ultrathink keyword’s reminder does not, so use an effort variant. Your own commands and skills (from .claude/commands, .claude/skills, your Claude config dir, or an enabled Claude Code plugin) still run when a message starts with their /name, from the first message (a plugin’s command once claudeCommands has listed it, else from the second message in a workspace). Headless transport only. See Your message reaches Claude as written.
webSearch "claude" | "disabled" | <tool> "claude" Routing for Claude’s built-in WebSearch. See WebSearch routing.
multiStepContinuation boolean true Append a system-prompt hint nudging Claude to chain tool calls within one turn instead of pausing between subtasks. Each opencode turn boundary requires the user to manually press “continue”, so for multi-step tasks this reduces friction. Set false to disable.
autoContinueIncompleteTurns boolean | "smart" "smart" Smartly continue incomplete Claude CLI results inside the same opencode turn. Reduces manual “continue” presses when Claude ends after reasoning/tool activity without a useful final answer. Also gates the ▌ **no reply:** note on a turn that ends with no text and no tool call. Set false to disable both.
compactionModel string "claude-haiku-4-5" Model used when opencode invokes /compact. Override per-process via the CLAUDE_CODE_COMPACTION_MODEL env var (env wins over config). See Compaction.
ignoreAnthropicApiKey boolean false Strip ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN from every spawned claude process so it authenticates with your logged-in subscription instead of pay-as-you-go API billing. The plugin warns once at startup whenever an API key is detected, regardless of this setting. See Billing.
idleProcessTimeoutMs number – Kill a retained Claude worker (headless or interactive) after this many idle milliseconds following a completed turn. The timer starts when a turn finishes, a new turn cancels it, a worker that is mid-turn when it fires is left alone and re-timed, and the session id is preserved for --resume. Values above Node’s maximum timer delay (2147483647) are ignored. Omit or set 0 to retain workers until LRU eviction (16 processes). On the interactive transport the TUI is closed and the next message starts a new one with --resume. Contributed by @bernardofortes.
bridgeOpencodeSkills boolean false Expose your opencode skills to Claude’s native Skill tool, from every root opencode itself reads. Off by default because every bridged skill is also in the system prompt opencode forwards, so a large set is paid for twice per turn; the bundled configuration skill is staged either way. See Skill bridge. Written by @broskees.
bridgeSkipNativeSkills boolean true Leave a skill unbridged when the Claude session already loads it from $CLAUDE_CONFIG_DIR/skills, the project’s .claude/skills, or an installed plugin, so one skill does not reach the model twice. Matched by resolved path, by identical SKILL.md, or by name. false bridges everything and reinstates the duplicates. See Skills Claude already has.
logging object all defaults The plugin’s own logger, four independent fields: file (boolean, default false), dir (string, default ~/.local/share/opencode-claude-code/), mode ("silent" | "debug", default "silent") and level ("debug" | "info" | "notice" | "warn" | "error", default "info"). Goes under provider.claude-code.options like every other row here. See Logging.
turnStats boolean false Append a one-line cost / duration / cache footer to each finished turn. See Per-turn stats.
enableTodoTools boolean false Start every claude with CLAUDE_CODE_ENABLE_TODO_TOOLS=1, so Claude Code offers its todo tools whatever the model. On its own it offers them only to Claude 3.x, Opus 4.0 to 4.7, Sonnet 4.0 to 4.6 and Haiku 4.5, so on Opus 4.8, the 5.x models and Fable no todo list reaches opencode without it. A CLAUDE_CODE_ENABLE_TODO_TOOLS already in opencode’s environment, 0 included, wins. Both transports; never on a compaction spawn. See Subagent todos.
forkSessions boolean false Branch a forked opencode session off the parent’s Claude conversation with --fork-session instead of replaying its history as text. A fork taken from a turn this opencode process served is already continued that way, cut at the turn, by forkFromCheckpoint; this option adds forks of a parent whose turn left nothing to cut at, and the interactive transport. See The prompt cache an agent writes.
forkCompaction boolean false Run /compact inside a fork of the chat’s own Claude session (--resume <id> --fork-session) on the chat’s own model, so the summary reads that session’s prompt cache and sees the whole thread, instead of a text transcript on compactionModel. Cheaper and more faithful on a warm cache with an inexpensive chat model, about even on Opus, dearer on a cold cache. Headless only; falls back to the transcript whenever it cannot fork. See Compaction on a fork.
forkOnRewind boolean true After an /undo, an edited message or a regenerated reply, continue a copy of the chat’s Claude session cut at the last turn both versions of the thread share (--resume <id> --resume-session-at <uuid> --fork-session), instead of ending the session and replaying the shorter thread as text. Each answered turn records where its reply ended in Claude’s transcript, and the copy holds exactly the turns that are left; the old transcript is never changed. Measured on Claude Code 2.1.288, 2.1.293 and 2.1.314 on a four-turn thread: 38 to 121 tokens written to the prompt cache against 11,152 to 20,659 for the replay, 6.9 to 9.7 times cheaper, faster every time, and the model kept a document line and a tool result that the replay’s clipping had dropped. Anything it cannot match falls back to the replay: no recorded turn that the thread now ends on, a transcript or entry that is gone, the interactive transport (Claude Code takes the cut in print mode only), Claude Code older than 2.1.288, an account in another accountGroups group, and compaction. Like any --resume, the copy keeps the system prompt the conversation started with. See Sessions.
forkFromCheckpoint boolean true When a new chat is forked from another one (“Fork from here”, /fork), continue a copy of the parent’s Claude session cut at the turn the fork was taken from (--resume <id> --resume-session-at <uuid> --fork-session), instead of replaying the inherited thread as text into a fresh session. The fork is recognised by content, on both opencode majors: its history has to match, reply for reply, a turn another chat in the same project served on the same model, agent and effort in this opencode process, and end on that turn’s reply. The parent’s transcript is never changed. Measured through opencode 2.2.6 and Claude Code 2.1.322 on Haiku 5.5, a 22 KB document and two codewords, forked before a third: 30 to 39 tokens written to the prompt cache against about 25,000 for the replay, 7.3 times cheaper (5.4 on opencode 1.19.4), and the fork quoted a line of the document that the replay’s clipping had dropped. Like any --resume, the copy keeps the system prompt the parent started with; a chat in the same project on the same agent gets the same prompt (byte-identical in the measurement), so what can differ is the date line and an instruction file edited since. After an opencode restart only a fork of the WHOLE conversation is continued (from the parent’s saved session, --resume <id> --fork-session, which needs resumeAfterRestart); a fork from an earlier message replays. Anything else it cannot match falls back to the replay too: a turn that ended on a tool call, the parent mid-turn, another account, a transcript that is gone, the interactive transport and Claude Code older than 2.1.288. See Sessions.
resumeAfterRestart boolean true After opencode restarts, resume a conversation’s Claude session with --resume instead of replaying the whole thread as text into a fresh one. After each successful turn, and after one that failed on a usage limit or an expired login (Claude Code keeps that message in the session), the session id and a digest of the conversation are kept in $XDG_STATE_HOME/opencode-claude-code-plugin/claude-sessions.json (0600, at most 256 conversations, 30 days). It resumes only for the same opencode session, model, agent and account, when the transcript is still on disk and the conversation is exactly the one recorded plus Claude’s reply; an edit, revert or compaction replays as before. opencode-dcp’s own additions to a message are left out of the digest: its <dcp-message-id> references, because dcp renumbers them when opencode restarts and a conversation that had an undo in it would otherwise never resume, and its <dcp-system-reminder> context-limit warning, because dcp appends that to messages already in the history and the message would otherwise look edited on the next turn. A digest written by an earlier plugin version is still compared the way it was written. opencode’s own <system-reminder> blocks are stored with the message, so they stay part of the digest. Like any --resume, the conversation keeps the system prompt it started with. false never reads or writes the file.
liveModelSwitch boolean true Apply a model or reasoning effort change to the conversation’s running claude process, with Claude Code’s own set_model and apply_flag_settings control requests, instead of stopping it and starting another with --resume. The conversation and the prompt cache are the same either way (measured on Claude Code 2.1.288 and 2.1.314); what it saves is starting a process, which took 4.6 to 6.6 seconds per change on a real install, against about 0.7 s for a model change and well under a second for an effort change. So that an effort change can apply, a headless spawn on Claude Code 2.1.288 or newer passes the effort as --effort and leaves CLAUDE_CODE_EFFORT_LEVEL out of the child’s environment, because that variable would silently override a live change. It applies only when the process is idle and the change is to the model (on the same account and in the same fast mode) or between two explicit effort levels; a change that arrives while a turn is still running applies from the next turn, as before. Anything else, a refusal, or no answer within CLAUDE_CODE_LIVE_SWITCH_TIMEOUT_MS, falls back to the respawn. The interactive transport always respawns. Needs resumeAcrossModelChanges; false restores the respawn and the environment-variable effort exactly.
resumeAcrossModelChanges boolean true When you change a conversation’s model or reasoning effort mid-conversation, continue the same Claude session (--resume <id> --model <new>) instead of replaying the whole thread as text. Both the model and the effort level are part of the session key, so changing either used to land a live conversation on a key nothing had answered; neither needs a new Claude conversation, because --model and CLAUDE_CODE_EFFORT_LEVEL are both applied at spawn time and the CLI accepts either on a transcript it resumes. The Claude session is moved off the old key rather than shared, so one conversation always has one owner. It refuses on everything resumeAfterRestart refuses on, plus a sibling whose transcript may still be written to (that turn finishes on the old process, and the change applies from the next one) and anything that is not the same request scope, opencode session and agent. A session opencode moved to another working directory (a session_move into a lane’s worktree, say) is carried the same way: its transcript is copied from the old directory’s project folder into the new one’s and resumed there, and a turn that was still running when the session moved finishes in the old directory first. A change to an agent’s prompt-cache TTL, maxTurns or maxBudgetUsd carries the conversation the same way; the new maxBudgetUsd counts from zero in the new process, as it does after any resume. Never on a compaction turn or an account switch. It reads the record resumeAfterRestart writes, which is also what carries the first change after an opencode restart, so resumeAfterRestart: false disables it too.
crossAccountResume boolean true On an account switch, whether you pick another account’s model by hand in the same session or through the switch form, and only between accounts in the same accountGroups group, continue the same Claude conversation on the other account instead of replaying the whole thread as text into a fresh session there. An account is a CLAUDE_CONFIG_DIR and a conversation is one transcript file inside it, so the switch copies that file into the target account’s own projects/<encoded cwd>/ (0600, never overwriting, never through a symlink) and spawns it with the --resume that already exists. Claude Code 2.1.288 resumes a copied transcript with its context intact and resolves a session by filename, so an older copy already sitting at the target path makes the carry take a fresh session id rather than overwrite it. The source transcript is never moved, emptied or written to. Any refusal falls back to the replay and says which in the log. Does nothing on a single-account install.
usageWarnThresholds number[] [50, 75, 90, 95] Usage levels, in percent of a usage window, at which a served turn ends with one ▌ **usage:** line: which account, which window, how much of it is used, and when it resets in your own time zone. Each threshold is said once per account per window (not again on the next turn, from another session, or after a restart) and again only after the window resets. Never on a /compact turn or in a subagent’s session. Read from Claude Code’s own usage reports, so the interactive transport (which gets none) only records a limit. [] turns the notes off; the readings are still kept for the sidebar and /claude-code-doctor. Works with one account. See Usage before the limit.
usageSwitchAt number | false 90 The usage level, in percent, at which work should leave an account before it hits the limit, when another account in the same accountGroups group is configured and is not itself at that level. With accountFailover: "auto", new turns move to that account until the window resets (the same account-wide switch a usage limit makes, held in memory), and the ▌ **usage:** line says so. With "ask" or "off" nothing moves and no form is raised: the line names the other account to pick a model from. The turn that crossed is never changed. false or 0 turns it off. See Usage before the limit.
loginExpiryWarnDays number | false 10 Days before an account’s claude.ai login ends at which a served turn ends with one ▌ **login:** line naming the account and the command that logs it in again, said once per login. The sidebar shows the date from the same day. Read from the date Claude Code 2.1.318+ puts on every answer; an API key reports none. Never on a /compact turn, a doGenerate call or in a subagent’s session. false or 0 turns the line and the sidebar line off. At most 30. See Before a login ends.
transport "auto" | "headless" | "interactive" unset (headless) Explicit transport selection, taking precedence over interactive and its env var. auto prefers headless and selects the PTY only when a free CLI help/argument probe proves the required headless flags unavailable. Timeouts, auth failures and unknown probe results stay headless; no submitted request is retried. Explicit interactive, or an automatic PTY selection, requires Bun.Terminal and fails clearly without it. /compact uses the selected transport. On opencode 2 set it in the plugin’s own options or use interactive, never in the provider block, where it clashes with opencode’s own transport setting. See Interactive transport.
interactive boolean false Legacy experimental PTY opt-in, used only when transport is unset. Explicit boolean wins over CLAUDE_CODE_INTERACTIVE_TRANSPORT; without Bun PTY support this legacy option still falls back to headless. Tool proxies work on both transports; permissionMode, /btw and MCP hot reload remain unavailable on the PTY. Plan mode and the read-only preset are refused rather than weakened.
interactiveBypass boolean false Deprecated no-op. skipPermissions governs the interactive transport too: with it on (the default) the TUI runs --dangerously-skip-permissions like headless, its confirmation skipped by Claude Code’s own skipDangerousModePermissionPrompt setting (CLI 2.1.263+).
interactiveAllowTools string[] ["Bash", "Edit", "Write", "Read", "WebFetch"] With the interactive transport, where the TUI does not run with --dangerously-skip-permissions (plan mode, controlRequestBehavior: "deny" aside, or a CLI older than 2.1.263): built-in tools pre-allowed without prompting (replaces the default list). MCP server wildcards (mcp__<server>__*) are always added from the bridged config.
interactiveSystemPrompt boolean true With interactive: append this plugin’s CLI/AGENTS/continuation prompt via --append-system-prompt-file. The transport intentionally does not forward opencode’s own system prompt, because it can trigger Claude Code’s third-party-app usage gate on subscription accounts. Set false only for diagnostics.
interactiveUserInstructions boolean false With the interactive transport: also append, verbatim, what you wrote that opencode forwards: each instruction file opencode loaded (Instructions from: <path>), counted only when that local file’s current content matches what opencode sent (trailing whitespace aside), and the active agent’s own prompt from your agent definition. CLAUDE.md files (the TUI loads those itself) and an AGENTS.md the plugin already appends are skipped. opencode’s own prompt, environment block and tool guidance are never forwarded. Headless is unaffected. Not tested against Claude Code’s third-party-app classification: if a turn is billed as one, turn it off.

Free and MIT-licensed, made by @khalilgharbaoui. If the plugin saves you time, you can buy its maintainer a coffee.

Buy me a coffee