Start from the symptom
Four checks answer almost everything, then a table keyed on the first thing you see.
Four checks answer almost everything. Run them in this order, and stop as soon as one of them explains what you are seeing.
| Check | What it tells you |
|---|---|
/claude-code-doctor in the session |
The plugin version actually loaded, the claude path and version, which providers and accounts registered, proxyTools, the permissionPreset per provider and what it replaced, the working directory and which rule picked it, every live claude child, and every pending proxy call. No model is called and nothing is billed. Start here. |
/claude-code-doctor bundle in the session |
The same report plus this process’s recent NOTICE/WARN/ERROR log lines, redacted by allowlist so you can paste the lot into a public issue. This is what to attach to a bug report. See Filing an issue. |
OPENCODE_CLAUDE_CODE_LOG_FILE=1 opencode, then grep ~/.local/share/opencode-claude-code/plugin.log |
Whether the plugin loaded at all, and every warning it emitted. The log file is off by default, so turning it on needs a relaunch. The raw log is not safe to attach to an issue: it has no redaction guarantee and can hold whole system prompts. Use /claude-code-doctor bundle for that. |
claude --version |
Whether a version-gated feature can work at all. Version floors: 2.1.142 thinking summaries, 2.1.220 fast mode, 2.1.258 /btw and --restricted, 2.1.263 --permission-prompts none, 2.1.280 claude-opus-5-5. |
claude auth status, or CLAUDE_CONFIG_DIR=~/.claude-<name> claude auth status |
Which account is signed in, and whether its login is still valid. |
Start from the symptom
| What you see first | The one check | The fix |
|---|---|---|
No claude-code provider or model in the picker at all |
Is there a plugin ready line in the log? |
None means the plugin never loaded, an older version means the package cache. See Nothing in the picker. |
Model unavailable for a model id you typed |
The providers field of the ready block, or the same line in /claude-code-doctor |
Use the provider id that line actually lists. With no accounts configured on opencode 2 the id is claude-code, so claude-code-default/<model> fails while the plugin is perfectly healthy (measured on opencode 2.0.16, 2026-09-27). Declaring accounts is what creates claude-code-default. |
opencode plugin list prints No plugins found, on opencode 2 |
/claude-code-doctor in a session, or opencode models | grep claude-code |
Not a fault: on opencode 2.1.4 that command does not list this plugin even while it is loaded and serving turns, and opencode plugin check / opencode plugin update do not see it either. If the doctor answers or the models are listed, the plugin is running. |
400 Third-party apps now draw from your extra usage… |
/claude-code-doctor for the account the conversation is on, then claude auth status for its plan |
An account-level usage gate, not a plugin fault: extra usage is off, or the window is exhausted. Wait for the reset, or move to another configured account. This is one of the two error texts the plugin recognises as a usage limit, so you get a ▌ **usage limit:** line naming the account and the local reset time rather than this raw text, and with "accountFailover": "ask" the switch form instead, or with "auto" the same request moved to the next account. Enabling paid usage or changing authentication is a billing decision and nothing here makes it for you. |
A reply that is only API Error: 529 Overloaded (or another API Error: sentence), kept like an ordinary answer |
The plugin version in /claude-code-doctor |
Resend when you are ready: Claude Code had already retried the request itself before giving up. Upgrade, and such a turn finishes as an error instead of an ordinary reply, with the sentence shown once. |
Your own /command is answered with “not installed” or “I don’t have a skill called…” |
Was the command file created after the conversation’s claude started? Is verbatimPrompts on? |
Claude Code reads its commands when it starts, so a file added mid-conversation runs from the next claude in that folder, a new session for instance. Older plugins also kept the mark on the first message in a folder, where a disable-model-invocation command never ran: upgrade. A Claude Code plugin’s /plugin:cmd runs from the first message once the plugin has listed it (claudeCommands, on by default). See Your message reaches Claude as written. |
A Claude Code skill or command such as /release “does not exist” in opencode, or the model answers that /test-cards is not available |
Is claudeCommands on (default)? Did opencode start after the skill was installed? Is the plugin that defines it enabled in Claude Code (claude plugin list)? |
opencode reads its / menu when it starts and the plugin lists what Claude Code listed at the previous start, so restart opencode once after installing a skill (on opencode 2, /reload twice). Typed, /release runs plugin:release when exactly one enabled plugin defines it and nothing else is called release; when two plugins define it, type the full /plugin:release. Headless Claude Code never resolves a short name itself. Log: read claude code's own commands from the cli, sending a claude code command under the full name it was listed with. See Claude Code’s own commands in the / menu. |
Tool result name changed, and the turn aborts, on opencode 2 |
The plugin version in /claude-code-doctor |
Fixed in 0.28.1: a CLI-executed tool’s result used to reach opencode under a different name than its call, and opencode 2.0.16 aborts the turn on that mismatch, which broke every Claude-side MCP server call. Upgrade, then fully quit and relaunch every opencode window: plugin code is read once at process start, so a new package in a running window changes nothing. |
Provider did not return a tool result on a tool row, on opencode 2 (or a row stuck pending on opencode 1) |
The plugin version in /claude-code-doctor |
Upgrade. A tool Claude Code ran itself used to lose its result at a step boundary: Claude Code answers a whole batch of tool calls with one message, so when one of them is proxied to opencode it holds its own results back, and the step has to end before they arrive. The same happened to a tool Claude Code refused, whose refusal arrives a frame early. The row now carries a result either way, and the model was never affected: it had the real output all along. |
| A sentence at the top of a reply that answers your previous message | Whether it is led by ▌ **between turns:** |
Working as designed. A reused claude process kept talking after the plugin had closed the turn, usually after a proxied tool call or a background command it started, and the next turn replays it under that note so it is not mistaken for this answer. It is stripped from any transcript rebuilt for the CLI. Older versions replayed it as bare text with nothing marking it, which is the same thing without the attribution. |
| After switching agents (plan to build, build to plan) Claude ignores what was just said under the other agent, or answers an earlier message | The plugin version in /claude-code-doctor |
Upgrade. Each opencode agent runs its own claude process, and before 0.55.0 a process reused after the other agent’s turns was sent only your newest message, so it carried on from its own last reply. It is now told what the conversation said while it was away, replayed as text ahead of your message, with a replaying the messages this claude session missed line in the log. The two processes are kept apart on purpose: a Claude session keeps the system prompt of its first request, so handing the plan agent’s session to the build agent would leave Claude under the plan agent’s instructions. |
After an /undo, an edited message or a regenerated reply, Claude still acts on the turns you removed |
The reply’s first line, and forking the claude session at the last turn the edited thread still has or replaying the conversation as text: the thread was edited or undone in the log |
Upgrade. A claude session cannot have messages taken back out of its context, so an older plugin left the reused process answering the thread you had edited away. The session is now dropped and replaced by a copy cut at the last turn the thread still has, or, where no such turn was recorded, by a fresh session the thread is replayed into, under a ▌ **conversation rewound:** note. One shape is deliberately left alone: an undo back to the very first message, or an edit of it, leaves nothing of the old thread in place, which is also what an opencode compaction looks like from here, and a compacted chat has to keep its process. |
A chat forked from another (“Fork from here”, /fork) no longer remembers a file it read or a long message from before the fork |
replaying the conversation as text in the log |
The inherited thread was replayed as text instead of continuing a copy of the parent’s session cut at that turn (forkFromCheckpoint). A reason that does not start with fork- (usually no-sibling-recorded) means no served turn matched: the parent’s turn was answered before opencode last restarted and the fork was taken from an earlier message (a fork of the whole conversation starts from the parent’s saved session after a restart too), ended on a tool call, or ran on another model, agent or effort, or the parent was mid-turn. A fork- token names a refusal after the turn was found: fork-interactive-transport, fork-cli-too-old (Claude Code older than 2.1.288), fork-transcript-gone, fork-entry-gone. |
| After an undo or an edit, Claude no longer remembers a file it read or a long message from earlier in the chat | replaying the conversation as text with a forkRefused token in the log |
The thread was replayed as text, which clips long messages and tool output, instead of continuing a copy of the session. The token says why: option-off (forkOnRewind: false), interactive-transport (the TUI cannot take the cut), cli-too-old (Claude Code older than 2.1.288), no-checkpoint (the thread now ends on a turn another agent or model answered, one that failed, or one from before Claude Code compacted the session itself), transcript-gone or entry-gone (the session’s transcript was cleaned up or no longer holds that turn). |
▌ **conversation rewound:** on turns where you undid and edited nothing, sometimes once a minute, each one slow and starting over |
The plugin version in /claude-code-doctor, and whether opencode-dcp is installed |
Upgrade. opencode-dcp appends its <dcp-system-reminder> context-limit warning to messages that are already in the history, so a message went out on one turn as you wrote it and came back on the next turn 1,091 characters longer, which read as you having edited it: the healthy claude session was dropped and the thread replayed as text. The digest now ignores dcp’s own blocks. opencode’s own <system-reminder> blocks are stored with the message and are still read, so a real edit is still caught. |
prompt is too long on the first turn after an opencode restart, or after a long session lost its Claude session, and /compact fails the same way |
The plugin version in /claude-code-doctor |
Upgrade. The text replay a fresh claude gets when no session can be resumed had no total size; a long session rebuilt a multi-megabyte first message. It is capped at 180,000 characters now, oldest messages first, and says [N earlier messages omitted ...] at the top when it had to. |
On opencode 2, every turn fails with ENOENT: no such file or directory, posix_spawn '<path to claude>' although that path exists, and only in a subdirectory of a project |
The plugin version in /claude-code-doctor; whether the session was opened below the project root |
Upgrade. Before 0.55.0 the plugin appended the session’s project-relative subpath to a directory that already was the session’s own, and spawned claude in a directory that does not exist. Setting cwd worked around it at the cost of pinning every session to one directory; remove that again after upgrading. |
Claude read a .env you expected opencode’s rules to protect |
/claude-code-doctor’s read-rules section: is *.env listed as an ask rather than a deny? |
opencode’s own default for *.env is ask, not deny, and an ask cannot be carried onto a spawn that has nobody to ask, so nothing is denied out of the box. Write permission: { read: { "*.env": "deny" } } (mapReadRules then carries it onto Claude’s Read), or add Read to proxyTools so opencode’s own prompt applies. See Read rules carried onto Claude’s own Read. |
Claude read a file an opencode read deny rule covers |
Whether the tool row is Claude’s own read rather than a proxied one, then the doctor’s read-rules section |
A deny should be carried across automatically. If the doctor lists it as unmapped (a .. in the pattern) or the pattern has a * mid-path, the rule is narrower on Claude’s side; set mapReadRules aside and proxy Read, or use permissionPreset: "read-only". |
A Claude Code hook on Bash, Edit or Write stopped firing |
Whether that tool is in proxyTools (the default list has all three) |
A proxied call reaches Claude as mcp__opencode_proxy__<tool>, so the matcher must name that: mcp__opencode_proxy__bash. Hooks on tools Claude still runs itself (Read) fire as before. |
| A Claude Code hook you configured has no effect, and Claude never mentions it | The Hooks Claude Code ran that failed section of /claude-code-doctor |
The hook exited non-zero, so Claude Code discarded its contribution and answered the turn anyway. The section gives the exit code and the hook’s stderr. Fix or remove it in your own Claude Code settings; only SessionStart and Setup hooks are visible here, because the plugin does not pass --include-hook-events. |
plugin ready is missing from the log |
That the log file is actually on, since it is off by default | If it is on and the line is still absent, the plugin never loaded. Check the package is in plugin (1.x) or plugins (2.x), that a local checkout points at dist/ on 2.x, and that you relaunched rather than opened a new session. /claude-code-doctor answers the same questions without enabling logging. |
Failed to authenticate: OAuth session expired, one account, every turn failing in milliseconds |
CLAUDE_CONFIG_DIR=~/.claude-<name> claude auth status for that account |
Log it in again. The plugin writes a ▌ **claude account:** note naming the account and the exact command, for example CLAUDE_CONFIG_DIR=~/.claude-work claude auth login, and offers the switch form when another account exists. Restart opencode afterwards: a switch made from that form lasts until opencode restarts. |
| A tool call reported as rejected although it really ran | The plugin version in /claude-code-doctor |
Upgrade to 0.26.2 or newer. Two separate causes, both fixed: opencode 1.18.32 aborts the provider signal of every step that ends in tool calls and the plugin read that as you pressing stop (0.26.1), and a call waiting on an unanswered permission prompt was rejected at the flat 10-minute deadline, after which your late approval cancelled Claude’s next call (0.26.2). A deadline now waits while opencode reports the session busy, so an unanswered prompt is never a reason to raise proxyToolTimeoutMs. |
proxy call still waiting in the log, or a task that looks stuck |
/claude-code-doctor, which lists every pending call with its tool, age and deadline |
Usually nothing is wrong. See A proxy call that will not finish. |
⚙ invalid or ⚙ unknown tool rows |
Which tool name the row carries | ⚙ invalid todowrite inside a subagent means that agent has no permission.todowrite: "allow"; see Subagent todos. Any other name is a Claude tool this plugin version does not map for your CLI version: record the plugin version, the CLI version and the tool name, and report it. A permanently pending ⚙ unknown row is the same problem in its older shape, an input delta for a call opencode never saw start. |
| No todo list, and the sidebar’s progress bar never shows a fraction | Which model the session runs | Claude Code offers its todo tools only to Claude 3.x and Opus 4.0 to 4.7, Sonnet 4.0 to 4.6 and Haiku 4.5. On Opus 4.8, Opus 5 and 5.5, Sonnet 5 and 5.5, Fable and Haiku 5.5, set enableTodoTools: true (or start opencode with CLAUDE_CODE_ENABLE_TODO_TOOLS=1 in its environment); see Subagent todos. |
A -fast model clearly ran at ordinary speed |
Grep plugin.log for fast mode |
Fast mode fails soft, so the plugin warns once per reason and names it; the CLI reports fast_mode_state: "off" on the turn’s terminal result, which is the frame the plugin reads (the one at session start is optimistic and can say "on" for a turn that was not fast). The usual cause is that usage credits are off (/usage-credits in an interactive claude). Also: a CLI below 2.1.220, a cooldown after a fast-mode rate limit, free tier or an organization that disabled it, CLAUDE_CODE_DISABLE_FAST_MODE=1, or a non-first-party route, since Bedrock, Vertex and Foundry are excluded. Until it is fixed, switch to the non-fast id so the picker’s price matches your bill. |
| An MCP server’s tools are simply absent | The WARN the plugin logs once per process at session start for the servers Claude Code could not connect (one line per status), or, for a claude.ai connector this account never connected, the doctor’s list of those |
Authenticate or repair that server where it is configured. mcpServers in the ready block is on-disk discovery, so a server can be listed there and still be unreachable. |
MCP server "<name>" is needs-auth in Claude Code, for a remote server that works fine in opencode |
Whether you authenticated it through opencode’s own OAuth flow | Expected: opencode holds that token, and the bridged config carries no credential, so the Claude CLI cannot connect. On opencode 1, bridgeMcpOauthTokens: true hands the CLI the token opencode already has. It is off by default because it copies a credential out of opencode’s store; read Servers you authenticated through opencode’s OAuth flow before turning it on. opencode 2 keeps those tokens elsewhere and the option finds nothing. |
| A freshly published version does not appear | The plugin version in /claude-code-doctor against the version you expect |
Remove the frozen cache entry and relaunch: see Nothing in the picker. If npm itself does not list the version, a registry proxy or local security scanner with a minimum-package-age policy can be filtering it out of the reply, sometimes for hours, so read that tool’s event log before blaming the registry. opencode caches whatever older version it resolved in the meantime, so delete the entry again once the new version is visible. |
permissionPreset is set but nothing about the session looks restricted |
The permissionPreset row in /claude-code-doctor, for the provider the conversation is actually on |
none there means the option never reached this provider: it belongs under provider.<id>.options, and with accounts configured each account is its own provider id. readonly (unknown, nothing applied) means the name is not one the plugin knows, so nothing was applied at all; the only name today is read-only. When it did apply, the Permission preset overrides block names every option it replaced. |
permissionPreset: "read-only" is set, but reads are not confined or something still prompts |
claude --version |
The preset holds on any CLI, but two of its four layers are version-gated: --restricted needs 2.1.258 and --permission-prompts none needs 2.1.263. Below those it falls back to --disallowedTools plus the plugin’s own denial of every permission request, and warns naming what is missing. Below 2.1.258 you lose the working-directory confinement on reads; below 2.1.263 the denial happens in the plugin instead of in the CLI, one layer instead of two. See Read-only mode. |
| A reply that is only “There’s an issue with the selected model (…). It may not exist or you may not have access to it.” | Whether that model id is in the picker, and claude -p --model <id> "hi" |
The CLI refused the model: it is retired, misspelled, or this account cannot use it. The result’s subtype is success, so without a chain the turn finishes as an ordinary reply with that sentence as the answer. Fix the id in the agent’s forceModel or in your picker, or declare a fallback model chain so the turn degrades to the next model instead of dying. |
▌ **model fallback:** on a turn you expected to run on a specific model |
The note itself, which names the model that failed and why | Working as configured: your fallbackModels chain moved the turn. model_not_found means fix the first id. out of usage on this account means that account’s cap, and the reason you got a chain rather than the account failover form is that the form is off (its default) or had no other account to offer. The chain never changes account, only model. |
| A reply that is only “API Error: Opus 5.5’s safeguards flagged this session…”, finished as an error | The model the conversation is on | A safety classifier stopped the reply twice. Claude Code’s own fallback to another model is off by default (CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK), so the turn ends here: rephrase, or pick another model. See Claude Code’s own fallbacks. |
▌ **refusal fallback:** in a reply, and the sidebar names a model you did not pick |
Whether CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK=0 is in opencode’s environment |
Working as configured: you kept Claude Code’s refusal fallback, so it answered on the model the note names and stays on it until the process restarts. Unset the variable to have a refusal end the turn instead. |
| After a usage limit you picked a model under another account, and Claude no longer knows the conversation | replaying the conversation as text with sibling-conversation-changed in the log |
Upgrade. The record that lets a switch carry the conversation to the other account was only written after a turn that was answered, so the limited turn’s message sat past it and the switch replayed the whole thread as text instead (bounded, so the oldest messages were dropped, and a guard hook may refuse the replay outright). A limited turn’s message is in Claude’s own transcript, so it is recorded now and the switch carries the session as it does at any other time. A restart after a limit replayed for the same reason and now resumes. |
▌ **prompt blocked:** instead of an answer, the turn marked as failed |
The quoted reason in the note, and which of your Claude Code UserPromptSubmit hooks wrote it |
Working as designed: one of your own Claude Code hooks (agent-guard, for one, refuses a prompt that looks like it holds a secret) ended the message before the model saw it, and no model was called. Send it again without what the hook objected to, or change the hook. When the note says the message carried the conversation’s earlier messages, it was the replay of the history after a model or account switch: that history did not reach Claude, so the next message replays it again, and the hook will judge it the same way. Switch back to the model or account that answered before to keep the history, or let the hook pass the replay. A message you sent while Claude was working gets the same note under an answer that did not see it. Older plugins showed ▌ **no reply:** for all of this, said nothing failed, and after a blocked replay sent every later message to a Claude session that held none of the conversation. |
| A turn that called a tool and then stopped with no answer and no error | The plugin version in /claude-code-doctor, and rendering a reply claude code sent without streaming in the log |
Upgrade. Claude Code had resent the call without streaming (a 404 on the streaming endpoint, or a stream cut early), and its whole-message reply was dropped. Now it is shown. |
| A chain is declared but a refused model still kills the turn | Grep plugin.log for fallback model refused: unknown model |
Every entry has to be a model id this plugin registers; an unknown one is skipped with that warning, and a chain whose entries are all unknown is an empty chain. The other empty-chain case is a list containing only the model the turn already runs on, which is dropped from its own chain. Compaction turns, title stubs and the interactive transport never fall back at all. |
| On opencode 2, a subagent you asked for on a particular model ran on another | The subagent’s tool row: does its input carry a model? |
No model there means Claude did not pass one, so opencode picked the model as usual. Name the model by its id in your message, such as claude-sonnet-5-5, or by its full reference for another account; see A model you name in the conversation. Before 0.60.0 the plugin’s task tool had no model at all. If the row does carry one and the subagent’s sidebar row shows a different model, that is a bug: attach /claude-code-doctor bundle to the report. |
| Invalid model “…” or Model “…” is not available on a subagent row, on opencode 2 | The model on that row |
Claude passed a reference opencode does not have, usually a guess at a model you named in words. opencode refused it before anything started, and Claude normally tries again. A bare id of a model this plugin registers is completed rather than refused, so on a current plugin this is a misspelt id, another account’s @ marker without its provider, or a guessed provider; an older plugin refused every bare id, so upgrade. Name the model by its id or full reference to skip the guessing. |
| A subagent dispatch refused with … which is outside this conversation’s account group, so no tasks were started | Your accountGroups |
Working as designed: the model sits on an account in another group, and a subagent carries this conversation’s task text with it. Name a model on an account in this conversation’s group, or set subagentDispatchCrossGroup: true if crossing groups is what you want. |
On opencode 1, Claude says its task tool cannot take a model, or a dispatch fails with This opencode’s task tool takes no per-call model |
opencode --version |
opencode 1’s task tool has no model field, so a subagent’s model cannot be chosen in the message there. Use an agent’s forceModel, defaultSubagentModel, or subagentDispatch: "ask"; see Subagents. |
▌ **restart opencode:** at the top of a reply |
The note itself, which names both versions and when this process loaded its build | Working as designed, and it is telling you something only it can see: opencode reads a plugin once, at process start, so this window is still running an older build than the one on disk. Quit every opencode window, serve and GUI processes included, and relaunch. It appears once per conversation and is stripped from any transcript rebuilt for the CLI. |
| A bug you are sure was fixed is back | The plugin build row of /claude-code-doctor |
The same cause, before the note has had a chance to appear: the window answering you predates the fix. The row names the version this process loaded, when it loaded it, and what is on disk now. A process that has been open for weeks can be weeks behind, and nothing else in opencode says so. |
| A config change did nothing | /claude-code-doctor, which reports the options in force |
Provider options are read once at opencode startup. Quit every opencode window, serve and GUI processes included, and relaunch. A /new session is not enough. |
| A question form never renders and the turn hangs | GET /question on the same opencode server and workspace |
See A question form never renders. |
Free and MIT-licensed, made by @khalilgharbaoui. If the plugin saves you time, you can buy its maintainer a coffee.
