OpenCode Goal Plugin

OpenCode Goal Plugin adds Codex-style long-running goal mode to OpenCode. It gives AI coding agents a /goal slash command, persistent goal state, completion evidence, idle continuation, and a terminal UI goal indicator so an OpenCode session can keep working toward one explicit objective until it is complete, blocked, or cleared.

If you are searching for an OpenCode goal plugin, goal mode for OpenCode, or a way to keep an OpenCode AI coding agent focused on a long-running task, this package is the npm plugin for that workflow.

Links:

• npm package: @prevalentware/opencode-goal-plugin
• GitHub repository: prevalentWare/opencode-goal-plugin
• OpenCode plugin command: opencode plugin @prevalentware/opencode-goal-plugin

The OpenCode Goal Plugin adds:

• /goal <objective> as an OpenCode command for TUI, desktop, and web.
• A sidebar goal indicator with status, elapsed time, and objective.
• Agent tools: get_goal, get_goal_history, create_goal, set_goal, update_goal_objective, update_goal, and clear_goal.
• Goal close evidence: complete requires verified evidence, and unmet requires a concrete blocker.
• Persistent per-session goal state with history, checkpoints, budgets, and owner-only file permissions.
• Optional automatic continuation on session.idle / session.status, with no-progress pause and budget wrap-up safeguards.
• Plan-mode safety: goals created from the plan agent stay paused, and auto-continue never escapes a Plan-mode session or switches agents on its own.
• Compaction context so active goals are preserved when OpenCode summarizes a long session.

Why Use This OpenCode Goal Plugin?

Use this plugin when you want OpenCode to behave more like a goal-driven coding agent instead of a one-prompt assistant. A goal stays visible, survives session compaction, can continue automatically when the session becomes idle, and can only be closed with explicit evidence or a concrete blocker.

Common use cases:

• Keep an OpenCode agent focused during long refactors, migrations, reviews, or test-fixing sessions.
• Track one explicit objective across TUI, desktop, and web OpenCode surfaces.
• Require completion evidence before a goal is marked done.
• Preserve the current goal when OpenCode summarizes or compacts a long conversation.

Install

Choose the instructions that match the CLI you run:

Do not mix the configuration formats. OpenCode 1 uses plugin and tui.json; OpenCode 2 uses plugins and the global cli.json.

OpenCode 1 Stable

Install for the current project:

opencode plugin @prevalentware/opencode-goal-plugin

Install globally:

opencode plugin -g @prevalentware/opencode-goal-plugin

OpenCode detects both package entrypoints and writes the plugin into the server and TUI config targets.

For manual installation, add the package to both V1 config files.

opencode.json:

{
  "plugin": ["@prevalentware/opencode-goal-plugin"]
}

tui.json:

{
  "plugin": ["@prevalentware/opencode-goal-plugin"]
}

OpenCode 2 Beta

Use this section only when running opencode2. Plugin release 0.1.30 and newer supports OpenCode 2 preview 0.0.0-next-17055 while remaining compatible with OpenCode 1.

Add the package to both V2 plugin lists:

opencode.json:

{
  "plugins": ["@prevalentware/opencode-goal-plugin"]
}

~/.config/opencode/cli.json:

{
  "plugins": ["@prevalentware/opencode-goal-plugin"]
}

OpenCode 2 does not read the V1 tui.json file. The server entrypoint comes from opencode.json, while the sidebar and palette integration come from ~/.config/opencode/cli.json.

OpenCode 2 plugin APIs are still beta. This package pins its V2 development contract to the preview version above; later previews may require a compatible plugin update. V2 currently supports the goal command, tools, persistent state, usage accounting, idle continuation, Plan-mode safety, and TUI sidebar/palette integration. Goal-specific compaction context and recovery of already-running child sessions after a plugin restart remain V1-only because the current V2 plugin context does not expose equivalent hooks or history queries.

Options

In OpenCode 1, server options use the package-and-options tuple in opencode.json:

{
  "plugin": [
    [
      "@prevalentware/opencode-goal-plugin",
      {
        "auto_continue": true,
        "defer_while_tasks_active": true,
        "max_auto_turns": 25,
        "min_continue_interval_seconds": 3,
        "max_turn_time": 300,
        "max_prompt_failures": 3,
        "default_token_budget": 200000,
        "max_goal_duration_seconds": 1800,
        "no_progress_token_threshold": 50,
        "max_no_progress_turns": 2,
        "restricted_agents": ["plan"],
        "allow_goal_execution_from_plan": false
      }
    ]
  ]
}

In OpenCode 2, use the plugin object form instead:

{
  "plugins": [
    {
      "package": "@prevalentware/opencode-goal-plugin",
      "options": {
        "auto_continue": true,
        "max_auto_turns": 25,
        "default_token_budget": 200000,
        "restricted_agents": ["plan"]
      }
    }
  ]
}

Defaults:

• auto_continue: true
• defer_while_tasks_active: true; when enabled, goal auto-continuation waits for active OpenCode Task child sessions and their orchestrator reconciliation before sending the next goal prompt.
• max_auto_turns: 25
• min_continue_interval_seconds: 3
• max_turn_time: unset by default; set a positive number of seconds to retry one active-goal continuation prompt when a model turn remains busy for that long. Each new busy event resets the watchdog. Idle, built-in retry, session deletion, active Task children, and restricted agents suppress the retry. Watchdog retries are independent of min_continue_interval_seconds and do not consume auto-turn, no-progress, or prompt-failure budgets.
• max_prompt_failures: 3
• default_token_budget: unset by default; when set, new goals inherit this token budget.
• max_goal_duration_seconds: unset by default; when set, new goals inherit this elapsed-time safety limit.
• no_progress_token_threshold: 50; output-token floor used to judge whether a goal continuation turn made progress.
• max_no_progress_turns: 2; consecutive low-progress goal continuation turns before pausing. Only turns produced by a reserved goal continuation count — ordinary low-output assistant messages (for example short tool-call-only turns from PTY or status checks) never increment this counter.
• register_command: true
• command_name: "goal"
• restricted_agents: ["plan"]; agents (matched case-insensitively) treated as planning-only for goal execution.
• allow_goal_execution_from_plan: false; when true, disables Plan-mode goal restrictions entirely.

Goal Workflow

Use /goal <objective> in a fresh OpenCode chat to create a long-running goal:

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

Bare /goal reports the current goal state. /goal history reports lifecycle history and recent checkpoints. /goal edit <objective> updates the current objective. /goal pause pauses the goal without clearing it, and /goal resume resumes it. /goal clear clears the goal; /goal stop, /goal off, /goal reset, /goal none, and /goal cancel are clear aliases. The TUI also includes a Goal command-palette entry for viewing, refreshing, pausing, resuming, showing history, or clearing the current goal state without creating a new goal.

You can also ask the agent to formulate the objective and call set_goal itself, for example: "set your own goal to finish this refactor safely." The tool uses the agent-written objective but still only creates a goal when explicitly requested.

When writing the objective, include the scope, non-goals, and verification path when they matter. The agent is reminded to audit real files, command output, tests, or PR state before closing the goal.

The update_goal tool can close a goal in two ways:

• status: "complete" with evidence when every requirement is actually achieved.
• status: "unmet" with blocker when the objective cannot be achieved or is blocked by missing external input.

The plugin also uses safety states while keeping the goal available for review or resume:

• budgetLimited when a token budget is exhausted.
• usageLimited when an auto-turn or elapsed-time budget is exhausted.
• paused when the user pauses, auto-continue repeatedly fails, or repeated low-progress goal continuation turns are detected. No-progress accounting is scoped to goal continuation turns: each reserved continuation is evaluated once, when its turn completes, and unrelated assistant activity in the session never pauses the goal.

When a safety limit is reached, the plugin sends one wrap-up prompt asking for a concise handoff instead of silently continuing forever.

Plan Mode Safety

OpenCode Plan mode is a user-controlled safety boundary, and goal mode must not become an escape hatch out of it. The plugin enforces that boundary in several layers:

• Goals