Common failures
| Symptom | Cause and fix |
|---|---|
OpenCode CLI is not installed | opencode is not on PATH. Install it, or pass an absolute path via --opencode-cli. |
OpenCode has no authenticated provider (warning) | Advisory only. Run opencode auth login if runs actually fail with a provider error. |
Requested OpenCode model is unavailable | The model is not in opencode models. Fix the name — the plugin will not substitute one. |
OpenCode produced an empty response | The turn returned no assistant text. Check stderr.txt in the artifact directory. |
OpenCode review timed out | Raise --timeout (default 900s). The process tree is killed and nothing is approved. |
OpenCode session could not be resumed | The session id is gone from OpenCode's store, or session export failed. Start a fresh review round. |
response contains no <OPENCLAUDE_RESULT> block | The model answered in prose. Usually a weaker model; pin a more capable one. |
PLAN.md changed after approval | Working as designed. Re-review the current plan. |
Build requires a clean checkout | Delegated builds need a clean tree. Use git worktree add; do not discard work. |
OpenCode ran against '…', not the requested repository | OpenCode resolved a different working directory. Report it with your OpenCode version. |
| Skills not showing after install | claude plugin details openclaude-loop, then restart Claude Code. |
Where to look first
Every run prints its artifact directory before launching. Read result.json there first — status, error, exit_code and stdout_events usually identify the problem immediately.
opencode run --format json streams JSONL, but a truncated run leaves partial lines — and an error event still carries a session id, so a session id proves nothing. The runner captures stdout, stderr and the exit code, parses events best-effort, then reads the authoritative transcript with opencode session export.
Contributing
See CONTRIBUTING.md for setup, the test contract, and the invariants a change must not break. Bug reports and feature requests use the issue templates.