prevalentWare/opencode-goal-plugin

OpenCode Goal Plugin – Keep an AI coding agent focused on a long‑running task

What it is – A plug‑in for the OpenCode AI‑coding environment that adds a goal‑mode. Users can start a persistent /goal <objective> that lives across the OpenCode UI (TUI, desktop, web) and survives session compaction. The goal stays visible in a sidebar, can auto‑continue when the session is idle, and can only be closed when the agent supplies concrete evidence of completion or a blocker.

Key features

• /goal slash command (create, view, edit, pause, resume, clear) – works in all OpenCode front‑ends.
• Sidebar indicator showing status, elapsed time, token usage and the objective.
• Agent‑side tools: get_goal, list_all_goals, create_goal, set_goal, update_goal, clear_goal, etc.
• Persistent per‑session state stored in $XDG_DATA_HOME/opencode-goal-plugin/goals.json (owner‑only permissions, atomic writes).
• Automatic continuation on session.idle/session.status with safety limits (token budget, time budget, no‑progress detection, max auto‑turns).
• Plan‑mode safety: goals created from the plan agent are paused and cannot auto‑continue unless the user explicitly allows it.
• Configurable options (auto‑continue, budgets, max turns, restricted agents, etc.) via OpenCode’s plugin configuration files.

Installation

• For OpenCode 1 (stable):

  opencode plugin @prevalentware/opencode-goal-plugin   # project‑local
  # or globally
  opencode plugin -g @prevalentware/opencode-goal-plugin
  

  Add the package name to opencode.json and tui.json under the plugin array.
• For OpenCode 2 (beta):

  {
    "plugins": [
      {
        "package": "@prevalentware/opencode-goal-plugin",
        "options": { "auto_continue": true }
      }
    ]
  }
  

  Place the entry in opencode.json (server) and ~/.config/opencode/cli.json (UI).

Typical workflow

1. Start a goal:

   /goal review the frontend and translate visible UI text to Spanish
   

2. The agent works on the task; the sidebar continuously shows progress.
3. When the objective is finished, the agent calls update_goal with status: "complete" and supplies evidence (e.g., test results, PR link).
4. If the goal cannot be met, the agent calls update_goal with status: "unmet" and a blocker description.
5. You can pause, resume, or clear the goal at any time with /goal pause, /goal resume, /goal clear.

Configuration highlights

• auto_continue (default true) – let the plugin keep prompting the agent when the session is idle.
• max_auto_turns (default 25) – caps how many auto‑continue prompts may run.
• default_token_budget – optional token limit for a new goal.
• restricted_agents (default ["plan"]) – agents that are treated as planning‑only; goals from them start paused.
• allow_goal_execution_from_plan – set to true to disable the plan‑mode restrictions (not recommended).

Safety mechanisms

• Budget limits – stop the goal when token or time budgets are exhausted.
• No‑progress detection – after a configurable number of low‑output continuation turns the goal is paused.
• Plan‑mode guardrails – prevents a planning session from silently turning into an execution session.

State persistence Goal data lives in a JSON file under the XDG data directory (or ~/.local/share/...), written atomically with owner‑only permissions. Crashes leave either the previous or the new complete state, enabling reliable recovery.

Development & publishing The repo uses bun for building and testing, and publishes automatically to npm via GitHub Actions with Trusted Publishing. The package exports separate modules for server hooks (./dist/server.js) and the TUI UI (./src/tui.ts).

---

Bottom line – If you use OpenCode for multi‑hour refactors, migrations, or test‑fixing sessions and want the AI to stay on a single, auditable objective, the OpenCode Goal Plugin provides a lightweight, configurable way to do that.