Repository navigation
Description
OpenCode Auto Advisor
Create @capybearista/opencode-auto-advisor, an OpenCode V2 plugin (server + TUI) that provides a Claude Code-style Advisor: an independent reviewer the agent can consult explicitly, plus automatic reviews triggered by an OpenCode Decision model.
Feature PR: #94 (draft, rebuilt on OpenCode 2.2.0)
Superseded: #61 (built on 2.0.21's Evaluation API, which OpenCode 2.2.0 removed), #54 (planning)
Design record: docs/auto-advisor/findings.md (spikes on real 2.2.0, live checks, recheck steps), plus the package README.md and AGENTS.md.
Current baseline
-
OpenCode V2 only: requires 2.2.0+ (
@opencode/plugin >=2.2.0 <3). No@opencode/aidependency. -
npm distribution channel:
latest, release classv2. -
One
opencode.json(c)pluginsentry loads both halves;cli.jsonneeds none. -
Explicit: a zero-argument
advisor()tool. The Advisor gets the agent's system prompt, tool names and transcript; its advice returns as the tool result. Unavailable in child sessions. -
Automatic: on each primary request, a Decision model (
ctx.experimental.generate.decisions, any catalog decision model) answers two questions in one call:moment:approach|stuck|done|routine(Claude Code's advisor moments);consequence: a 0–4 stakes score with fixed anchors.
The plugin consults the Advisor when 1 − P(routine) ≥
momentThresholdand the raw score ≥consequenceThreshold. -
Explicit and automatic paths share one stateless Advisor consult (
generate.text). -
Advisor model: inherits the agent's model and variant unless
advisor.modelis set;provider/model#variantpicks a reasoning level. -
Delivery (cache-safe): an accepted review goes to the tail of the current request and into an
auto-advisorinstruction entry for later steps. The system prompt is never edited. Each new review replaces the entry; it stays until superseded, including through session compaction. -
Advisor context: OpenCode's Code Mode tool catalog, MCP server instructions and skill catalog are replaced with
[context-omitted: …]markers in the Advisor's copy (on by default); the transcript is capped atadvisor.maxTokens(default 64000), dropping middle turns. -
Routing modes:
off(default),observe(Decision only, logged),active. -
Budget:
routing.maxConsultationsPerTurnautomatic consults per user turn (default 2). Explicit calls do not count. -
Decision fallback: ordered
routing.models(default["opencode/jev-1.13-free"], works without a Zen login). The host retries rate limits and overload; the plugin moves to the next model on availability or auth failures and fails open when the chain is exhausted. -
Telemetry: JSONL at
~/.local/share/opencode/auto-advisor/telemetry.jsonl(5 MB, one rotation). Never transcript or advice text. -
TUI: a footer status ("Advisor reviewing…" / "✓ Advisor reviewed (moment)" / "Advisor unavailable") and the latest review above the composer. Driven by RPC events; the server works without the TUI.
Configuration
Optional, sparse, strict JSON at ~/.config/opencode/auto-advisor.json (or $OPENCODE_CONFIG_DIR / $XDG_CONFIG_HOME/opencode). No file means all defaults; an omitted key means its default. An invalid file turns automatic reviews off and makes advisor() return the error. Secrets do not belong in the file. Changes apply without a restart.
Nine knobs:
| Key | Default |
|---|---|
advisor.model |
inherit |
advisor.timeoutMs |
300000 |
advisor.compactContext |
true |
advisor.maxTokens |
64000 |
routing.mode |
off |
routing.models |
["opencode/jev-1.13-free"] |
routing.momentThreshold |
0.7 |
routing.consequenceThreshold |
1.5 |
routing.maxConsultationsPerTurn |
2 |
Execution contracts
- [Auto Advisor] Establish core Advisor and routing foundation #48: Core Advisor and routing foundation (closed)
- [Auto Advisor] Add Decision-model automatic routing and delivery #50: Automatic routing and delivery (rebuilt on 2.2.0 in feat(auto-advisor): rebuild Auto Advisor on OpenCode 2.2.5 #94)
Consolidated issues:
- [Auto Advisor] Establish routing domain and mode control #49 -> [Auto Advisor] Establish core Advisor and routing foundation #48
- [Auto Advisor] Add active automatic consultation and system-context delivery #51 -> [Auto Advisor] Add Decision-model automatic routing and delivery #50
- [Auto Advisor] Integrate release policy, documentation, and v1 readiness validation #52 -> [Plugin]: OpenCode Auto Advisor #47/[Auto Advisor] Add Decision-model automatic routing and delivery #50 final-readiness work
Final readiness checklist
- rebuild on 2.2.0 approved and implemented in feat(auto-advisor): rebuild Auto Advisor on OpenCode 2.2.5 #94
- spikes on real 2.2.0: Decision API, delivery, reentrancy, explicit tool, protocol lowering (
findings.md) - package README and package-local contributor guidance
- root documentation updated for implemented behavior
- package registered in release-channel policy/guard and tests
- changeset decision (ship unpublished
2.0.0as-is, or aminorchangeset for2.1.0) - package-root runtime smoke passes
-
off/observe/activeruntime matrix (mock executor + real Jev) - interrupt during a consult: aborted, nothing delivered, telemetry
stale - live in a real TUI session: explicit
advisor(), invalid-config error,#variantreaches the provider,compactContext(~14k → ~6.8k tokens),maxTokenscap -
bun run typecheck && bun run lint && bun run test && bun run buildgreen; CI and CodeQL green - USER live test of automatic reviews:
observetelemetry,activefooter/panel, interrupt, advice uptake - live checks still open: session compaction keeping the entry, child sessions, fallback to a second real decision provider
- feat(auto-advisor): rebuild Auto Advisor on OpenCode 2.2.5 #94 ready for review, merged, npm publish confirmed
Follow-ups (not blocking)
- Calibrate thresholds from
observetelemetry. - Show config errors in the TUI footer (automatic reviews still switch off silently).
- The run-end event loop stops for good if one
iterator.next()rejects (review finding, deferred).
Activity