An experimental session-scoped /goal command 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: tested against OpenCode 1.15.11. The plugin relies on experimental OpenCode hooks; pin or re-test against your OpenCode version before using it for unattended long-running work.
npm install opencode-goal-pluginAdd 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"
}
}
}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
Flags accept either --flag value or --flag=value. If a flag is unknown, missing a value, or given a non-positive integer, 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
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.
- 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.
- 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.
- The plugin stops auto-continuing when the assistant ends a response with
[goal:complete]or[goal:blocked], or when a safety limit is reached.
The plugin stops when it sees one of these at the end of an assistant response:
[goal:complete]
[goal:blocked]
[goal:complete] — goal is satisfied.
[goal:blocked] — the assistant needs input from you. The line immediately before the marker explains the specific blocker; /goal status shows it while the goal remains in memory.
Markers must appear on their own final line. The bracketed form is canonical, but the plugin also accepts bare goal:complete and goal:blocked final lines because some models omit brackets. Natural-language phrases like "goal complete" are intentionally ignored.
| Limit | Default |
|---|---|
| Auto-continue turns | 10 |
| Max duration | 15 minutes |
| Tracked tokens | 200,000 |
| Min delay between continues | 1.5 seconds |
| No-progress pause | < 50 output tokens on a stalled turn (after a 2-turn grace window) |
| Budget wrap-up threshold | 80% of tracked token budget |
| Auto-continue failure pause | 3 consecutive prompt failures |
Effective turn count. Each LLM turn on a real task typically takes 30–90 seconds. At that latency, raising --max-minutes is usually more useful than raising --max-turns. At 45 s/turn, the default 15-minute window gives roughly 15–20 turns of headroom before the turn limit becomes the binding brake.
Token budget. The plugin tracks input + output + reasoning tokens across all session messages. In high-context sessions (large codebases, long conversation history), input overhead per turn can be substantial and the budget may be exhausted before the turn limit is reached. Treat it as a safety brake, not precise billing accounting.
No-progress heuristic. A low-output turn does not pause immediately anymore. The plugin pauses only after noProgressTurnsBeforePause consecutive stalled low-output turns — repeated turns with very little output and no meaningful change in the latest assistant checkpoint.
Wrap-up vs. hard stop. When a limit is reached, the plugin sends one final prompt asking the assistant to summarize what is done, what remains, and the next concrete step — rather than stopping silently. Use /goal resume to continue after any stop, including limit stops and no-progress pauses.
Goal state is persisted by default to ~/.opencode-goal-plugin/state.json, but only as a local workflow checkpoint. It is not synchronized across machines or OpenCode instances.
The state directory is created with owner-only permissions, and the JSON state file is written as 0600 because it may contain goal text, assistant checkpoints, and workflow history.
Recovered active goals are loaded in a paused state with a recovery note, so unattended auto-continue does not resume blindly after a restart. Set "persistState": false to keep purely in-memory behavior.
/goal resume continues the same objective with a fresh local budget window. This lets you continue after pause, blocker, no-progress pause, rate-limit failures, or a limit stop without retyping the objective.
Override any limit for a single goal:
| Flag | Controls |
|---|---|
--max-turns <n> |
Auto-continue turn limit |
--max-minutes <n> |
Duration limit in minutes |
--max-duration-ms <n> |
Duration limit in milliseconds |
--max-tokens <n> |
Tracked token limit |
--cooldown-ms <n> |
Minimum delay between continues |
--no-progress-threshold <n> |
Output token floor before pausing |
--no-progress-turns <n> |
Consecutive stalled low-output turns before pausing |
Examples:
/goal fix tests --max-turns 20 --max-tokens 400000
/goal fix tests --max-turns=20 --max-tokens=400000
/goal fix tests --no-progress-threshold 50 --no-progress-turns 2Pass options when registering the plugin to change the defaults for all goals. To combine with the goal command, merge this plugin entry into the config shown above.
{
"plugin": [
[
"opencode-goal-plugin",
{
"maxTurns": 10,
"maxDurationMs": 900000,
"maxTokens": 200000,
"minDelayMs": 1500,
"maxRecentMessages": 50,
"noProgressTokenThreshold": 50,
"noProgressTurnsBeforePause": 2,
"budgetWrapupRatio": 0.8,
"maxPromptFailures": 3,
"persistState": true,
"stateFilePath": "/home/you/.opencode-goal-plugin/state.json",
"resultRetentionMs": 604800000,
"maxStoredResults": 200
}
]
]
}Additional plugin-level options:
maxRecentMessages— how many recent session messages to scan when looking for the latest assistant turn before auto-continuing. Higher values make long, tool-heavy sessions less likely to lose the most recent assistant response.noProgressTurnsBeforePause— grace window for low-output stalls. The plugin pauses only after this many consecutive stalled low-output turns rather than on the first one.persistState— whether to persist active goals and recent goal results to disk.stateFilePath— where the persisted state JSON is written. Useful if you want per-project or ephemeral storage.resultRetentionMs— how long a completed goal summary remains available through/goal statusafter the goal leaves active memory.maxStoredResults— maximum number of completed-goal summaries retained in process memory before the oldest ones are evicted.
The goal text is wrapped in <goal_objective> tags and labeled as user-provided task data. The assistant is told to treat it as a task description, not as elevated instructions that can override system, developer, tool, or repository policies.
This is a marker-based implementation. The assistant is responsible for outputting [goal:complete] or [goal:blocked] — there is no independent evaluator verifying completion against the original goal. Claude Code's native /goal uses a separate evaluator model; this plugin currently approximates the workflow using OpenCode hooks and explicit completion markers. A future version could add a separate evaluator once OpenCode exposes a clean plugin API for that flow.
OpenCode's current command.execute.before hook does not fully intercept command text. The plugin can update in-memory goal state as a side effect, but the goal text may still be routed into the normal assistant conversation alongside the state update.
The plugin depends on experimental.chat.system.transform and other OpenCode plugin hooks that may change between OpenCode versions.
Point OpenCode at the source file directly for local testing:
{
"plugin": ["file:///absolute/path/to/opencode-goal-plugin/src/goal-plugin.js"]
}Keep test files outside OpenCode's auto-loaded plugin directory — OpenCode will attempt to load plugin-like files it finds there.
- Install or file-load the plugin in a temporary OpenCode config.
- Add a
goalcommand with"template": "$ARGUMENTS". - Run
/goal status— should report no active goal. - Run
/goal inspect this repo and stop immediately with [goal:blocked] if you need user input. - Verify
/goal status,/goal pause,/goal resume, and/goal clearbehave as expected.
npm test # run the test suite
npm run test:coverage # run tests with coverage
npm run check # syntax check + tests
npm run pack:check # verify package contents before publishingMIT