Long-running goal mode for OpenCode, built on the
@opencode-ai/plugin framework.
The plugin implements a goal state machine across the two plugin runtimes:
| Step | Where | Mechanic |
|---|---|---|
| 1. Command registration | Server plugin | /goal <objective> and /goalie registered in the config hook via config.command |
| 2. Refinement hook | Server plugin | command.execute.before feeds the objective to the plan subagent (client.session.prompt) and parses its structured JSON execution plan |
| 3. TUI interactivity | Server+TUI plugin | The server publishes tui.command.execute (goalie.review.<token>); the TUI plugin listens on the event bus and opens an Agree / Regenerate / Cancel dialog. The decision is written back to a pending-review file that the server polls while the command hook awaits |
| 4. Store + begin | Server plugin | On Agree the goal is persisted as pending (~/.local/share/opencode-goalie/state.json). It is NOT executing yet. A bare /goal begins it |
| 5. Auto-continuation | Server plugin | Once active, every session.idle re-prompts the model with the goal plus AGENTS.md; each turn's end reason is logged and counted |
| 6. Halt / complete | Server plugin | mark_goal_complete(evidence) closes the goal. The loop also halts when any single stop reason recurs stop_limit (default 10) times; the active goal is injected into the system prompt for all future turns |
/goal "arg" ──► plan subagent ──► structured plan ──► [TUI dialog] ──► Agree ──► stored (PENDING)
│
/goal (bare) ◄───────────────────────────────────────────────────┘
│
▼
begin (ACTIVE ─► injected into system prompt)
│
turn ends ──► log reason ──► same-kind count >= 10? ──► HALTED (run /goal to resume)
│ │
└──► re-prompt with goal + AGENTS.md objective met ──► mark_goal_complete(evidence) ──► COMPLETE
/goal <objective>
│
▼
┌─ draft plan (plan subagent) ─┐
│ │ Regenerate (max N times)
│ ▼
│ draft plan again
▼ │
[Agree / Regenerate / Cancel] ◄──────┘
│ │ │
Agree│ │Cancel │
▼ ▼ ▼
persist no-op stores nothing
as PENDING
│
│ /goal (bare)
▼
ACTIVE ──► injected into system prompt every turn
│
│ every turn end (session.idle):
│ ├─ log stop reason (ended / cancelled / error / exhausted / complete)
│ └─ re-prompt with goal + AGENTS.md (unless halted/complete)
│
├─ any single kind × stop_limit (default 10) ──► HALTED (must /goal to resume)
└─ mark_goal_complete(evidence) ──► COMPLETE ──► injection stops
Each turn's end reason (from the assistant message finish/error) is recorded
in stopHistory and counted per-kind in stopCounts. When any one kind hits
stop_limit, the autonomous loop stops to prevent infinite looping.
Once mark_goal_complete(evidence) runs, the goal is set to complete and the
loop is permanently shut down for it:
- The tool returns a result that instructs the model to stop immediately and
give a brief final summary. It intentionally does not call
session.abort: that is an out-of-band async request which races the agent loop, either killing the tool mid-execution (losing its result and marking the turn aborted) or landing one step too late after the model has already resumed generating. The goal state itself is what shuts the loop down. maybeContinuereturns immediately forcompletegoals — no further continuation prompts are ever sent (re-verified atomically before each send).experimental.chat.system.transformstops injecting the goal (onlyactivegoals are injected).get_goalreturns the completed goal (status: "complete"+ evidence) so a model "looking for its goal" can see it is done instead of gettingnull.mark_goal_completeis idempotent: repeat calls return{ ok: true, already_complete: true }without aborting again, so the model won't retry in a loop.
src/
types.ts shared types (GoalState, ExecutionPlan, PendingReview, …)
state.ts atomic JSON persistence + pending-review channel (shared by both processes)
prompts.ts planning prompt, plan parser, system-prompt block, command template
server.ts server plugin: command hook, refinement, review orchestration, tools, injection
tui.ts TUI plugin: plan-review dialog (Agree / Regenerate / Cancel)
test/
goalie.test.ts unit tests (parser, state, review channel)
integration.test.ts end-to-end /goal → review → persist → complete flow
Server-side options are read from the tuple form of the plugin entry.
| Option | Default | Description |
|---|---|---|
command |
"goal" |
Slash command name |
goalieCommand |
"goalie" |
Companion command name for status/clear/settings |
agent |
"plan" |
Planning subagent used to refine objectives |
review_timeout_seconds |
120 |
How long /goal waits for the TUI decision before treating it as cancelled |
poll_interval_ms |
250 |
Decision-poll rate while awaiting the TUI |
max_regenerations |
3 |
Times "Regenerate" re-runs the planner before forcing a cancel |
min_continue_interval_seconds |
3 |
Minimum gap between two autonomous re-prompts |
stop_limit |
10 |
Auto-continuation halts when any single turn-end reason recurs this many times |
max_prompt_failures |
3 |
Auto-continuation halts after this many consecutive failed prompt sends |
agentsmd_limit |
12000 |
Max chars of AGENTS.md included in continuation prompts |
Example opencode.json:
And the TUI half in tui.json (REQUIRED for the review dialog):
{
"$schema": "https://opencode.ai/tui.json",
"plugin": ["/home/you/opencode/goalie/src/tui.ts"]
}The TUI plugin is what turns the review into a real interactive dialog. Without it,
/goalstill works but the review silently times out and cancels.
- In a session, run
/goal ship the auth refactor. - The
plansubagent drafts a structured plan, which pops up in a review dialog:- Agree — the goal is stored as pending (not started).
- Regenerate — the planner drafts a new plan.
- Cancel — nothing is stored.
- Run
/goalwith no arguments to begin. The goal becomes active and is injected into the model's system prompt. - From then on, every time the model finishes a turn the plugin logs the
reason the turn ended (e.g.
ended,cancelled,error,exhausted,complete) and re-prompts the model with the goal plus AGENTS.md. If any single stop reason repeatsstop_limittimes (default 10), the autonomous loop halts so it can't run forever — run bare/goalto resume. - When the objective is met, the model calls
mark_goal_complete(evidence). The goal closes, its evidence is recorded, and it is no longer injected into the system prompt.
/goal stays a clean two-function command (set, then start). Inspection and
lifecycle controls live in the companion /goalie command:
| Command | Effect |
|---|---|
/goalie or /goalie status |
Report the current goal (status, objective, plan, stop counts, evidence) or say none is set |
/goalie clear |
Remove the current goal for this session (any status) |
/goalie settings |
Show the effective plugin settings |
/goalie help |
Show usage |
Both commands are registered by the plugin's config hook. Rename them with the
command and goalieCommand options.
bun install
bunx tsc --noEmit # typecheck
bun test # run the test suiteRestart opencode (or reload plugins) after changing plugin config.
{ "$schema": "https://opencode.ai/config.json", "plugin": [ ["/home/you/opencode/goalie", { "review_timeout_seconds": 180, "max_regenerations": 5 }] ] }