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 and the goal command to opencode.json (the user config at ~/.config/opencode/opencode.json, or a project-local opencode.json):

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

Or let the CLI add the plugin entry for you and then add the command block by hand:

opencode plugin opencode-goal-plugin@0.10.0 --global

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

Upgrading

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.10.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 objectives that auto-promote one at a time, use /goal sequence. Multi-word values must be quoted.

Flags accept either --flag value or --flag=value. If a flag is unknown, missing a value, given a non-positive integer, or (for --mode) an unrecognized mode, the plugin rejects the command with a helpful error instead of silently folding the bad flag into the goal text.

To include literal command-line options in an objective, wrap them in a Markdown fenced code span. Double-dash tokens inside the fence are objective text and are not parsed as goal flags:

/goal run ```pytest --maxfail=1 --disable-warnings``` and fix every failure

Multiline fences work as well. The backticks are removed from the stored objective, and a fence is never consumed as a flag's value.

Check status:

/goal status

/goal status keeps its existing Active goal: heading and adds an explicit State: line: active while the goal can continue, blocked when the assistant recorded a concrete blocker, and paused for other retained stops such as user intervention, a safety limit, or an audit rejection. A Completion audit: line distinguishes the always-on evidence gate from an optional built-in