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

Manually tested via the OpenCode TUI (tmux + real provider credentials, no mocks), verified against the plugin's own persisted state rather than terminal display alone:

/goal status and auto-continue are graded on state correctness (verified directly against the plugin's persisted state file: correct limits parsed, correct turn/stop accounting, correct completion detection) — not on what's rendered in the terminal, since that's tracked separately as Hook Output Display.

Note: Hook output display depends on OpenCode version — on 1.17.15, command.execute.before's output.parts text is not rendered in the TUI for any provider tested; the raw command argument is instead routed to the model as a normal chat turn (see Limitations). State mutations always work regardless of display: goal creation, flag parsing, auto-continue, limit enforcement, and evidence-gated completion detection were all verified correct via the persisted state file in every combination above. Re-test against your own OpenCode build before relying on unattended runs, and see docs/providers.md for the full per-model marker-compliance notes.

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 (alias sisyphus); ordered asks the assistant to work through the objective as a strict 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

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 the active goal:

/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 the numbered live goals (which is focused, which are backgrounded) and a per-session archive of completed/cleared goals so they stay readable. /goal focus <number> switches the active goal, backgrounding the previous one. Focus is tracked per session and survives a restart.

Ordered (sisyphus) sequences

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

/goal sisyphus 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-promotion stops when the sequence is exhausted; /goal clear ends the sequence.

Examples

Copy-pasteable goals for common workflows:

/goal "fix the failing tests" --max-turns 10
/goal "refactor auth to use new API" --max-minutes 30
/goal "audit for security issues" --max-turns 3
/goal "migrate class components to functional" --max-minutes 60 --max-tokens 400000

With success criteria, constraints, and a token budget shorthand:

/goal "ship the release" --success "tests pass and changelog updated" --constraints "do not touch the public API" --budget 150k

An ordered sequence, run as a strict pipeline:

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

How it works

1. When you set a goal, the plugin stores it in session memory and injects it into the system prompt so the assistant keeps it in view on every turn.
2. Each time the session goes idle, the plugin sends a continuation prompt containing the goal, the remaining budget, and a completion audit asking the assistant to verify the current state before declaring done.
3. The plugin stops auto-continuing when the assistant ends a response with a substantiated [goal:complete] or [goal:blocked], or when a safety limit is reached. A [goal:complete] is only honored when it is preceded by a [goal:evidence] line; a [goal:blocked] is only honored when a concrete blocker is stated. Unsubstantiated claims are rejected and the plugin re-prompts for the missing evidence or blocker.
4. If OpenCode compacts the session, the plugin injects a deterministic summary into the compaction context so the goal survives the compaction and the assistant keeps the thread. The summary — objective, status, budget u