Skip to content

About

Another mostly working /goal plugin for opencode.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

opencode-goalie

Long-running goal mode for OpenCode, built on the @opencode-ai/plugin framework.

How it works

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

State machine

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

Completion is terminal — no re-prompting

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.
  • maybeContinue returns immediately for complete goals — no further continuation prompts are ever sent (re-verified atomically before each send).
  • experimental.chat.system.transform stops injecting the goal (only active goals are injected).
  • get_goal returns the completed goal (status: "complete" + evidence) so a model "looking for its goal" can see it is done instead of getting null.
  • mark_goal_complete is idempotent: repeat calls return { ok: true, already_complete: true } without aborting again, so the model won't retry in a loop.

Files

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

Configuration

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:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    ["/home/you/opencode/goalie", { "review_timeout_seconds": 180, "max_regenerations": 5 }]
  ]
}

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, /goal still works but the review silently times out and cancels.

Usage

  1. In a session, run /goal ship the auth refactor.
  2. The plan subagent 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.
  3. Run /goal with no arguments to begin. The goal becomes active and is injected into the model's system prompt.
  4. 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 repeats stop_limit times (default 10), the autonomous loop halts so it can't run forever — run bare /goal to resume.
  5. 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.

The /goalie command

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

Development

bun install
bunx tsc --noEmit   # typecheck
bun test            # run the test suite

Restart opencode (or reload plugins) after changing plugin config.

About

Another mostly working /goal plugin for opencode.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages