Skip to content

[Plugin]: OpenCode Auto Advisor #47

Open

Description

@capyBearista

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/ai dependency.

  • npm distribution channel: latest, release class v2.

  • One opencode.json(c) plugins entry loads both halves; cli.json needs 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) ≥ momentThreshold and 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.model is set; provider/model#variant picks a reasoning level.

  • Delivery (cache-safe): an accepted review goes to the tail of the current request and into an auto-advisor instruction 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 at advisor.maxTokens (default 64000), dropping middle turns.

  • Routing modes: off (default), observe (Decision only, logged), active.

  • Budget: routing.maxConsultationsPerTurn automatic 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

  1. [Auto Advisor] Establish core Advisor and routing foundation #48: Core Advisor and routing foundation (closed)
  2. [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:

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.0 as-is, or a minor changeset for 2.1.0)
  • package-root runtime smoke passes
  • off / observe / active runtime 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, #variant reaches the provider, compactContext (~14k → ~6.8k tokens), maxTokens cap
  • bun run typecheck && bun run lint && bun run test && bun run build green; CI and CodeQL green
  • USER live test of automatic reviews: observe telemetry, active footer/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 observe telemetry.
  • 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).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions