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

Surface Status

Node.js Declared support: >=18; CI covers Node 18, 20, 22, and 24

Operating systems Filesystem-sensitive lifecycle tests run on Linux, macOS, and Windows

Package entrypoint Installed-tarball contracts verify both export paths, consumer TypeScript resolution, hooks, and all 11 tools

Provider/backend quirks Strict-template backends require the goal block to merge into the primary system message; covered by regression tests

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

OpenCode version compatibility

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

OpenCode Version Provider Tested /goal status Auto-continue Evidence-gated completion Historical custom-command presentation (v0.6.6)

1.17.15 opencode (deepseek-v4-flash-free) ✅ Canonical tool ✅ Checkpoint + idle continuation ✅ Structured goal_complete claim ⚠️ Command text routed to model; mutation guard verified

1.17.15 opencode-go (qwen3.7-plus) ✅ ✅ ✅ Self-corrected after one rejection (bare [goal:complete] with no evidence), then completed cleanly ⚠️ Not displayed

1.17.15 opencode-go (glm-5.2) ✅ ✅ ✅ Clean [goal:evidence] + [goal:complete] on the first attempt ⚠️ Not displayed

1.17.15 deepseek (deepseek-chat) ✅ ✅ ✅ Clean [goal:evidence] + [goal:complete] on the first attempt; also verified end-to-end via the demo — autonomously fixed a real bug and reported evidence-backed completion ⚠️ Not displayed

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

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

npm install opencode-goal-plugin

Add the plugin and command to your OpenCode config:

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

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

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.

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 independent verifier or custom completion auditor.

View lifecycle history and the latest checkpoint:

/goal history

Resume a paused or stopped goal:

/goal resume

Edit the active goal's objective without losing its budget or history:

/goal edit fix the failing tests and also update the docs

/goal edit <new objective> revises the goal in place: the turn, token, and time budget plus the lifecycle history are preserved, and any pause/blocked state is cleared so the revised goal can continue. A goal that already hit a hard limit will re-pause on the next idle — run /goal resume for a fresh budget window.

Pause without clearing the active goal:

/goal pause

Clear all live goals in the current session and discard their saved status:

/goal clear

/goal stop, /goal off, /goal reset, /goal none, and /goal cancel are aliases for /goal clear.

Session forks and child sessions

Goals are scoped to the session where they were created. A child session or a fork does not automatically inherit its parent's active goal; set a goal in the new session when you want it to continue independently.

This isolation is intentional. OpenCode currently includes parentID for ordinary child sessions but does not expose the source session in the session.created event for forks. Inferring ancestry from a mutable title such as (fork #1) could attach a goal to the wrong session. Automatic inheritance can be added once the host exposes an explicit fork relationship.

Multiple goals

A session can hold more than one goal. /goal <condition> replaces the focused goal, while /goal add <condition> keeps the current goal (backgrounding it) and focuses a new one. Only the focused goal is auto-continued; backgrounded goals are paused until you focus them.

/goal add write the migration guide
/goal list
/goal focus 1

/goal list shows numbered live goals (focused and backgrounded) plus achieved goals retained in the per-session archive. Each live entry includes its explicit active, paused, or blocked state; a stopped focused goal keeps its bounded stop or blocker reason visible. /goal clear intentionally removes live goals and saved status from these views; its terminal ledger entries remain available for crash-safe recovery decisions. /goal focus <number> switches the active goal, backgrounding the previous one. Focus is tracked per session and survives a restart.

Ordered sequences

/goal sequence sets up a strict execution queue: separate objectives with ; or newlines, and the plugin runs them one at a time, focusing the next as soon as the current one completes.

/goal sequence build the parser; write the tests; ship the release

The first goal is focused and the rest are queued. /goal list marks the session as ordered. Auto-