OpenCode Goal Mode

Simple Goal Mode for OpenCode.
One primary agent, one small server plugin, three tools — no npm sidebar, no command guard, no reviewer army.

What it is

You pick the goal agent and give a real task. When the work deserves a finish line, the agent calls goal_set with a verifiable condition (tests green, file exists, command output shows X).

After each turn the session goes idle. A separate evaluator model reads the transcript and answers:

• YES — condition met → goal cleared, loop stops
• NO — not yet → plugin sends a short continuation prompt and the goal agent keeps going

That is the whole product: work → idle → judge → continue or stop.

Casual chat without goal_set behaves like a normal agent — no hidden loops.

OpenCode layout

OpenCode loads this from your config directory:

~/.config/opencode/
  agents/goal.md              # primary agent (goal_set / goal_clear / goal_status via tools)
  plugins/goal-mode.js        # server plugin entry
  plugins/goal-mode/          # plugin implementation
  opencode.jsonc              # register the plugin (see below)

No TUI plugin. No tui.json entry for goal mode. The plugin id is opencode-goal-mode (server only).

Register the plugin

In opencode.jsonc (paths relative to that config dir):

{
  "plugin": [
    [
      "./plugins/goal-mode.js",
      {
        "evaluatorModel": "your-provider/your-model-id"
      }
    ]
  ],
  "default_agent": "goal"
}

evaluatorModel is optional — empty means reuse the same model as the goal session.

Install (npm – recommended)

npm install -g opencode-goal-mode

The post-install step prints a one-liner. Run it:

opencode-goal-mode-install --global --link     # symlinks (recommended)
# or
opencode-goal-mode-install --global            # copy install

Restart OpenCode.

Uninstall (npm)

opencode-goal-mode-install --global --uninstall   # removes only files it owns
npm uninstall -g opencode-goal-mode

If you manually added files later, delete them from ~/.config/opencode/agents/ and ~/.config/opencode/plugins/.

From this repo (dev)

node scripts/install.mjs --global --link   # symlinks
node scripts/install.mjs --global          # copy + manifest

Same uninstall command works.

How to use

1. Open OpenCode TUI (or opencode run -a goal "…").
2. Agent goal (Tab if needed).
3. Describe work; the agent calls goal_set with a measurable condition when there is a real finish line.
4. Agent uses normal tools (bash, edit, …); no slash command — only tools + this agent.
5. Let turns complete; auto-continue only happens while a condition is active on the goal agent.
6. goal_clear or “stop the goal” ends the loop.

Plugin tools: goal_set, goal_clear, goal_status.

Good conditions can be checked from the conversation: command exit codes, test output, file contents.

Configure

See CUSTOMIZE.md. Short version:

| Key | Default | Meaning | | --- | --- | --- | | enabled | true | Master switch | | evaluatorModel | (session model) | provider/model for YES/NO | | maxTurns | 0 | Cap auto-continues (0 = unlimited) | | noProgressLimit | 3 | Pause if evaluator repeats the same NO | | abortSuppressMs | 120000 | After user cancel, no auto-continue | | idleGraceMs | 1200 | Wait after idle before evaluating | | maxConditionLength | 4000 | Max chars in a goal_set condition | | transcriptMaxChars | 24000 | Max transcript chars sent to evaluator | | idleTimeoutMs | 120000 | Cap one idle-resolve attempt | | evaluatorRetryLimit | 5 | Retries when evaluator is unavailable | | evaluatorRetryIntervalMs | 15000 | Delay between those retries | | completionMarker | Goal Completed | Fallback if evaluator unavailable |

Environment: GOAL_MODE_* mirrors keys (GOAL_MODE_EVALUATOR_MODEL, etc.).

How it really works

Read GOAL.md for the user-facing walkthrough, or ARCHITECTURE.md for hooks and code layout.

Development

npm ci
npm test
npm run lint

Publishing (maintainers)

• Tag a release: git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z
• The publish.yml workflow runs on the tag and publishes to npm.
• README + package.json already expose the opencode-goal-mode and opencode-goal-mode-install bins.

License

MIT