An OpenCode V2 plugin that gives the agent a second opinion and a way to keep working until a goal is met.
- Native
advisorsubagent: runs in the background like every OpenCode subagent and reports back when idle, with a bounded parent-evidence snapshot and read-only tools. OpenCode owns the child lifecycle and continuation; this plugin supplies evidence and model selection. Configure anadvisorsubagent in your agents directory. The oldoracle_asktool is no longer registered. /advisor: shows or sets the advisor model./goal <what done looks like>: the agent works turn after turn. After each turn the advisor judges from the transcript whether the goal is met, blocked, or still missing something. Rounds are unlimited by default. The loop stops when the goal is done, and pauses when the agent is blocked, makes no progress for 3 rounds, or hits an explicit-nround limit.
opencode plugin add github:c0dn/opencode-advisorRequires OpenCode 2.3 or later (subagents always run in the background). The package has a server part (the tool, the goal loop and an RPC) and a TUI part (the slash commands, dialogs and toasts). OpenCode loads both automatically.
/advisor show the advisor model and where it is set
/advisor <provider/model[#variant]> set it for this project
/advisor --global <provider/model[#variant]> set the default for all projects
/advisor reset [--global] clear the project (or global) setting
/goal <goal> start working autonomously
/goal -n <count> <goal> the same, with a round limit
/goal show the current goal
/goal stop drop the goal (the turn in progress finishes)
/goal resume [-n <count>] unlimited, or count additional rounds
Goals survive an OpenCode restart. Round updates appear as toasts, and as a desktop notification while the terminal is in the background.
Set "external_judge": false in this plugin's options to skip goal verdict
model calls. The default is true, preserving independent judging. In judge-free
mode, an idle turn continues the goal until the agent calls
goal_complete({summary: "…", verification: "tests/checks and their results"}).
The completion tool is only exposed in this mode and rejects inactive goals,
registered waits, and blank evidence. Evidence is reported by the agent, not
independently validated. Round limits and interrupted-turn handling still apply;
advisor-based stall detection is unavailable. Use /goal stop when blocked.
goal_wait still suspends continuation while background work runs.
/advisor off blocks native advisor invocations for this project, including
explicit model overrides and follow-ups. /advisor on re-enables them without
changing the selected model. Add --global to set the default for all projects;
an explicit project setting takes precedence. /advisor displays both the
consultation status and goal judge mode. /advisor reset [--global] clears both
model and consultation overrides for that scope, restoring inheritance.
These switches are independent: /advisor off does not disable goal verdicts,
and external_judge: false does not disable manual consultations. To avoid both
kinds of advisor-model calls, use both settings. Turning consultations off blocks
new requests; it does not cancel an already-running request.
goal_wait and goal_complete are offered only in a session whose goal is
running or waiting. Other sessions, including every subagent, never see them:
a subagent that must wait for long work arms its own automation_create, which
wakes that subagent, and its next idle report reaches the parent.
When no independent work remains, call goal_wait and end the turn. Waiting uses no
model calls or goal rounds. goal_wait only pauses judging; it never delivers
results. Delivery is OpenCode's own and happens per item, as soon as each one
finishes, so a long subagent can never hold back another result. Failure and
cancellation are evidence for the parent, not success.
ids takes any mix of:
- Shell IDs and child sessionIDs from background launches in this session, e.g.
goal_wait({ids: ["sh_…", "ses_…"], reason: "need test and research results"}). They live inside the OpenCode server, so a restart, or the server dropping a shell when it unloads an idle project, loses them. - Automation ids (
aut_…) from OpenCode'sautomation_create(enable"experimental": { "schedules": true }). OpenCode renamed schedules to automations in Nov 2026; oldersch_…ids still bind and match the renamed wake. Use these for anything long or restart-sensitive: training, long evals, remote jobs. Automations are stored in OpenCode's database and fire even if the server restarted in between. There is nountilshell check any more, so use aneverytrigger whose prompt checks the job's log:
setsid -f bash -c 'python train.py --run 3 >/abs/run3.log 2>&1; echo EXIT=$? >>/abs/run3.log' </dev/nullthen automation_create({name: "run3", trigger: {type: "every", every: "10 minutes"}, action: {type: "prompt", prompt: "If /abs/run3.log has an EXIT= line, read it and continue; otherwise do nothing and end the turn."}})
and goal_wait({ids: ["aut_…"], reason: "run3 training"}). A remote job needs no local
process at all: have the prompt run the remote status command.
The wake is a normal message, so it arrives whatever state the goal is in. Calling
goal_wait again replaces the judging list and never cancels a delivery. Judging
resumes once every listed id has been delivered and handled by a parent turn. A
subagent report tagged state="running" (the child still owns a running shell,
image or nested subagent) is interim; the wait continues until its final report.
A child waiting on its own schedule cannot be told apart from a finished one, so
for such work arm a schedule in the parent on the same check and wait on that.
Lost and expired dependencies. A shell or subagent is lost when a different OpenCode server process is running than the one that launched it, or when its shell output file disappears (after a 30s grace). Schedules are never lost. A lost dependency, or one still open at the deadline, gets one reconcile turn telling the agent to check the real state before relaunching anything. If the same dependency is lost or expires again, the goal pauses.
The default deadline is 24h (timeoutSeconds: up to 7 days, or 30 days when every id
is a schedule). /goal resume overrides a wait and resets the reconcile allowance;
/goal stop stops the goal without touching background work. Waits persist across
plugin and OpenCode restarts. Waits saved by older versions on detached jobs are
dropped with a notice. Do not wait on a persistent dev server itself.
Each advisor child prompt receives a snapshot of its recorded parent's active
context (after compaction), not arbitrary sessions or hidden reasoning. The snapshot
is capped at 160k characters, with individual results clipped and omissions marked.
Follow-up prompts add only evidence since the saved message boundary (including
that boundary's potentially updated tool results). Compaction that removes the
boundary causes a fresh bounded snapshot. Model/tool steps do not append it again.
An explicit native subagent model override wins over /advisor settings.
Advisor and researcher permission hooks deny mutation, shell, nested delegation and approval-dependent actions. Use read/glob/grep and Keenable retrieval (Proteus hosted web tools need no permission); have the parent run authenticated CLI checks. Configure their agent permissions deny-first as well. No custom child runner, polling scheduler or log-monitor plugin is needed.
Waiting checks run at most every five seconds without model calls. A native
completion delivered without parent resumption deliberately remains waiting until the
parent handles it or the deadline queues a reconcile turn. Common credential paths are
denied, but read/search access is not an OS sandbox; do not use these roles for
untrusted agents. src/oracle.ts is retained as an unregistered legacy helper
and regression fixture, not exposed as a tool.
The advisor model is resolved in this order: the /advisor project setting, the --global setting, the plugin's advisorModel option, then OpenCode's default model. Pick a stronger model than the one doing the work.
Telling the agent when to use it helps. For example, in AGENTS.md:
- Call native `advisor` for consequential uncertainty, repeated failures or independent
verification. It reports back when idle; end the turn if you have nothing else to do.
- Call `goal_wait` before ending a goal turn solely to await background work: shell IDs or subagent sessionIDs for short work; for anything long or restart-sensitive, launch it detached, arm `automation_create` with an `every` trigger whose prompt checks the job's log, and wait on the automation id (`aut_…`).
- A message starting `[goal round N/M]` comes from `/goal`: keep working and show verifiable evidence.bun install
bun test
bun run typecheckPoint OpenCode at a checkout with a file:// entry in opencode.json plugins. Releases are published to npm by GitHub Actions when a GitHub release is created. The tag must match package.json's version, e.g. v0.1.0.
{ "plugins": [{ "package": "@c0dn/opencode-advisor", "options": { "advisorModel": "anthropic/claude-opus-4-1" } }] }