opencode-goal-plugin

A session-scoped /goal workflow for OpenCode.

Set a goal and the plugin keeps it in context, auto-continues the session whenever the assistant goes idle, and stops when the goal is marked complete, a blocker is reported, or a safety limit is reached.

Compatibility: this plugin relies on experimental OpenCode hooks. Re-test against the exact OpenCode build and provider/backend stack you plan to use for unattended work.

What it provides

• Session-scoped goals that remain visible across turns and compaction.
• Guarded auto-continuation with turn, duration, token, no-progress, and no-tool-call limits.
• Project-local restart recovery backed by persisted state and a bounded lifecycle ledger.
• Evidence-gated completion with an optional independent, fail-closed verifier.
• Explicit active, paused, and blocked status plus transition-only lifecycle notices.
• Canonical agent tools, collision-safe goal/verifier agents, multiple goals, and ordered goal sequences.

This project is independently implemented for OpenCode. Product names used elsewhere identify their respective owners; no feature-parity or endorsement claim is implied.

Compatibility snapshot

See the compatibility policy for the supported public surface and versioning expectations.

OpenCode version compatibility

Tested against real OpenCode 1.17.15 and 1.18.25 processes with live provider credentials and no mocked plugin hooks. State, ledger entries, and workspace files were checked independently of terminal or model prose:

/goal status and auto-continue are graded on state correctness (verified directly against persisted state: correct limits, turn/stop accounting, completion state, and file effects), not on terminal rendering. The deepseek-v4-flash-free canary suite additionally covers pause/resume across processes, blocker/restart, hard-process recovery, real host compaction, and stale-history clear enforcement. See docs/providers.md for the complete lifecycle matrix and session evidence.

Note: The table records the v0.6.6 live-provider matrix. In that release, OpenCode 1.17.15 retained the original command-parts array, so assigning a new output.parts array did not replace the raw command argument sent to the model. The current implementation mutates that retained array in place, making the plugin-generated command result the prompt for the turn. OpenCode custom commands still run through the model rather than rendering hook output directly, so the visible response may summarize or paraphrase the result (see Limitations). Re-test against the exact OpenCode build and provider/backend stack you rely on for unattended work, and see docs/providers.md for the full historical model matrix.

The 1.18.29 row comes from a deterministic-provider canary against a real opencode serve process, graded on persisted state. That canary also reproduced the two defects fixed in 0.10.0 (a first-command Plan goal not being held; a stale running title after completion) on 1.18.25 and 1.18.29 alike.

Separately, the lifecycle-feedback implementation included in v0.7.0 passed a real OpenCode 1.18.11 host canary covering create, status, pause, resume, edit, and default lifecycle logging with a deterministic localhost provider. That canary validates host integration, not another live-provider compatibility row.

Install

OpenCode installs npm plugins itself from your config, so there is nothing to npm install. Add the plugin with a pinned version to opencode.json (the user config at ~/.config/opencode/opencode.json, or a project-local opencode.json):

OpenCode 2 — the plugin registers its own command, so no command entry is needed:

{
  "plugins": ["opencode-goal-plugin@0.11.0"]
}

OpenCode 1 — the same plugin also needs its goal command declared in config:

{
  "plugin": ["opencode-goal-plugin@0.11.0"],
  "command": {
    "goal": {
      "description": "Set a session-scoped goal and auto-continue until complete.",
      "template": "$ARGUMENTS",
      "agent": "build"
    }
  }
}

A V1 config keeps working on OpenCode 2 (the plugin key is normalized to plugins), but its command.goal entry is registered after plugin commands on V2 and would shadow the plugin handler — remove it. The plugin detects the conflict, re-asserts its own registration, and logs a warning if a foreign definition still owns the name.

Or let the CLI add the plugin entry for you:

opencode plugin opencode-goal-plugin@0.11.0 --global

Restart OpenCode after editing the config. The options form ["opencode-goal-plugin@0.11.0", { ... }] (see Options) pins the same way.

Upgrading

For 0.11.0, use the config for your OpenCode version above and restart OpenCode. When moving from OpenCode 1 to 2, remove the legacy command.goal entry so the plugin owns /goal. Upgrade every process sharing the same goal state before resuming work; recovered active goals load paused and require /goal resume.

The release adds OpenCode 2 support and fixes Plan activation, stale completion approvals after objective edits, invalid completion evidence, and persistence on filesystems with capped timestamps or unsupported hard links. See the changelog for the full changes.

Pin the version. OpenCode resolves an unpinned "opencode-goal-plugin" entry to @latest exactly once, installs it under its package cache (~/.cache/opencode/packages/opencode-goal-plugin@latest/ by default; opencode debug paths prints the cache root), and never re-resolves latest while that directory exists. An unpinned entry therefore stays on whichever version was first installed, indefinitely, and new releases on npm are never picked up — a bug fixed months ago can still be running locally.

To upgrade, bump the pin (for example to opencode-goal-plugin@0.11.0) and restart OpenCode; every pinned version gets its own cache directory. If you kept an unpinned entry, delete the opencode-goal-plugin* directories under the cache packages/ folder and restart. npx opencode-goal-plugin runs the bundled verification script, which warns when the cached copy lags the package.

Usage

Set a goal:

/goal fix the failing tests and verify the suite passes

Override limits for a single goal:

/goal fix the failing tests --max-turns 20 --max-minutes 30 --max-tokens 400000 --max-cost 5

Add success criteria, constraints / non-goals, and a mode:

/goal ship the release --success "tests pass and changelog updated" --constraints "do not touch the public API" --mode ordered

--success (alias --success-criteria) and --constraints (alias --non-goals) take quoted text and are injected alongside the objective so the assistant keeps them in view. --mode is normal (default) or ordered; ordered tells the assistant to preserve step order inside one objective. To queue distinct objec