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>, /pause_goal, and /resume_goal as OpenCode commands for TUI, desktop, web, and remote integrations that expose the server command catalog.
• A sidebar goal indicator with status, elapsed time, and objective.
• Agent tools: get_goal, get_goal_history, list_all_goals, create_goal, set_goal, update_goal_objective, update_goal_status, update_goal, stop_goal, replace_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 releases from the feat/v2-adaptation line support OpenCode 2 beta 0.0.0-beta-19425 (the current @opencode/cli@beta / @opencode/plugin@beta contract) 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 beta 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, TUI sidebar/palette integration, goal compaction context, and transcript-based task recovery. Goal compaction context is injected through the V2 session.compaction hook on hosts that provide it (newer than beta-19425); on older betas the registration degrades to a no-op. After a plugin or server restart, V2 rebuilds Task-subagent deferral state by replaying each non-closed goal session's persisted transcript, because the V2 plugin context exposes no live child-session query; children that leave no finalized tool entry in the transcript are only observed through live events.

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_task_block_seconds": 900,
        "max_prompt_failures": 3,
        "locale": "zh-CN",
        "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,
        "max_objective_chars": 100000
      }
    ]
  ]
}

In OpenCode 2, use the plugin object form instead:

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

For OpenCode 1, server and TUI plugins are configured separately. To force the TUI to the same locale, use the same option in tui.json:

{
  "plugin": [
    [
      "@prevalentware/opencode-goal-plugin",
      {
        "locale": "zh-CN"
      }
    ]
  ]
}

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. A deferral re-checks child sessions on a short timer, so a goal deferred by a task never depends on a further idle event to resume.
• max_task_block_seconds: 900; wall-clock ceiling on how long a single Task child session may defer goal continuation. A child that stays listed but never reports a terminal state, or a terminal child whose result is never reconciled, stops blocking once the ceiling passes. Set a smaller value for shorter subagents, 0 to remove the ceiling, or disable deferral entirely with defer_while_tasks_active: false.
• max_auto_turns: 25; explicitly resuming a goal with /goal resume or /resume_goal after it reaches this limit starts a fresh auto-turn window. Token usage and elapsed-time usage are preserved.
• min_continue_interval_seconds: 3
• Fast V2 executions that finish inside this interval schedule a delayed continuation; they do not require another user message to wake up.
• 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 never consume auto-turn or no-progress budgets, but recognized transport failures still count toward the max_prompt_failures ceiling.
• max_prompt_failures: 3; consecutive transport or no-response continuation failures pause the goal at this ceiling. Prompt delivery alone does not reset the count; substantive assistant or tool progress, a new goal, or an explicit resume does.
• 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.
• locale: "en" by default. Set "zh-CN" for Simplified Chinese, or "auto" to detect LC_ALL, then LANG, then the OS/JavaScript runtime locale. Unsupported explicit locales fall back to English.
• register_command: true; registers /goal, /pause_goal, and /resume_goal.
• command_name: "goal"; renames the main goal command only. The reserved names pause_goal and resume_goal fall back to goal so the standalone controls remain ava