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, create_goal, set_goal, update_goal, and clear_goal.
• Goal close evidence: complete requires verified evidence, and unmet requires a concrete blocker.
• Persistent per-session goal state.
• Optional automatic continuation on session.idle.
• 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

Install locally for the current OpenCode 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.

Manual Config

If you configure it manually, add the package to both config files.

opencode.json:

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

tui.json:

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

Options

Server options can be configured in opencode.json:

{
  "plugin": [
    [
      "@prevalentware/opencode-goal-plugin",
      {
        "auto_continue": true,
        "max_auto_turns": 25,
        "min_continue_interval_seconds": 3,
        "max_prompt_failures": 3
      }
    ]
  ]
}

Defaults:

• auto_continue: true
• max_auto_turns: 25
• min_continue_interval_seconds: 3
• max_prompt_failures: 3
• register_command: true
• command_name: "goal"

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

State

Goal state is stored at:

$XDG_DATA_HOME/opencode-goal-plugin/goals.json

If XDG_DATA_HOME is not set, the default is:

~/.local/share/opencode-goal-plugin/goals.json

Set OPENCODE_GOAL_STATE_PATH to use a custom file.

Development

bun install
bun test
bun run lint
bun run typecheck
bun run build
npm pack --dry-run

Publishing

This package is set up for npm Trusted Publishing from GitHub Actions. On every push to main, CI runs typecheck, lint, and unit tests in parallel. If they all pass, the publish job computes the next patch version from the latest version on npm, builds the package, and runs npm publish.

Before the first automated publish, configure the package on npm:

1. Open the package settings on npmjs.com.
2. Add a Trusted Publisher for GitHub Actions.
3. Use repository prevalentWare/opencode-goal-plugin.
4. Use workflow file publish.yml.

The repository must be public for npm provenance to be generated automatically.

Notes

OpenCode plugin modules are target-specific. This package exports separate modules for server hooks/tools and TUI UI:

{
  "exports": {
    "./server": "./dist/server.js",
    "./tui": "./src/tui.tsx"
  }
}

Codex goal mode has deeper runtime integration for thread lifecycle control. This plugin implements the same workflow using OpenCode plugin hooks. Token usage is read from OpenCode step-finish usage when available and falls back to message token metadata or text estimation when exact usage is unavailable. Continuation is driven by OpenCode idle events, including session.idle and session.status idle notifications.

The goal sidebar shows the current status, elapsed time, auto-continue count, latest status message, and objective when a goal is active or paused. Closed goals remain visible briefly through the latest tool state as achieved or unmet.