opencode-goal-plugin

A /goal command for OpenCode: set an objective, walk away, and the plugin keeps the agent working until it proves the goal is done, reports a blocker, or hits a limit you set.

[!IMPORTANT] Maintenance only. OpenCode ships its own /goal as of v2.2.1 (2026-10-29, #59437). On 2.2.1 and later, use the built-in command unless you need what it does not do: evidence-gated completion with an independent read-only verifier, multiple goals and ordered sequences, configurable turn, time, token and cost limits, agent tools, and Plan-mode holds. Bug and security fixes only; no new features. Running both side by side: see Install.

Why it existed. From May to October 2026 OpenCode had no way to run an objective unattended. This plugin filled that gap for OpenCode 1 and 2, and was used for multi-hour autonomous runs in which no model could declare itself finished without evidence.

Engineering highlights

• Fail-closed persistence. Atomic state writes, an append-only lifecycle ledger for recovery, and a per-session lease built on immutable claim files. A second process on the same session stays passive instead of writing a diverging copy; unknown or corrupt layouts are quarantined, never silently rewritten. How it works
• Independent verifier. A goal is archived only after a separate child session, default-deny with read, glob and grep, reviews a structured completion claim and answers [audit:approved]. Verifier failures reject by default; a verifier whose prompt or permissions were changed always rejects. Completion auditor
• Mutation contract. npm run test:mutation applies the 94 named regressions in scripts/mutation-contract.mjs (fail-open audits, lost leases, resurrected goals, …) one at a time and fails the release unless a test catches every one.
• Cross-platform CI. The unit suite runs on Node 18–24 on Linux; the filesystem-sensitive lifecycle and lease tests also run on macOS and Windows. npm run release:check adds coverage, consumer TypeScript compilation against the packed tarball, installed-package host and tool contracts, a deterministic behavior benchmark and npm audit. ci.yml
• One core, two hosts. OpenCode 1 and OpenCode 2 load the same entrypoint; src/v2-bridge.js adapts OpenCode 2's hook domains onto the V1 hook contract, so the state machine, persistence and tools are shared code, not a fork.
• Real-host acceptance without paid models. npm run smoke:v2-host drives a real opencode serve with a localhost deterministic model provider; the same approach was used for multi-hour goal soaks with injected write failures and mid-goal reloads.

Try it: demo/ is a failing test suite and one /goal that fixes it.

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

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.

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.4"]
}

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

{
  "plugin": ["opencode-goal-plugin@0.11.4"],
  "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.4 --global

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

Running alongside the built-in /goal

OpenCode 2.2.1 and later ship a built-in /goal. With default options this plugin takes over /goal and the built-in command does not run. To keep both, se