opencode-goal

Long-running /goal support for OpenCode, inspired by Codex CLI goals.

Features

• /goal <objective> to set or replace a session goal.
• /goal, /goal status, /goal set <objective>, /goal edit <objective>, /goal pause, /goal resume, and /goal clear.
• Model tools: get_goal, create_goal, and update_goal.
• Per-session persisted goal state in .opencode/state/goal-plugin.json.
• Token accounting from OpenCode assistant message events, plus elapsed-time accounting from session activity.
• Automatic continuation when a session becomes idle and the goal is still active.
• Budget-limited wrap-up prompt when a goal reaches its token budget.

Install From npm

After publishing this package to npm:

opencode plugin opencode-goal --global

Restart OpenCode after installing.

The plugin auto-registers the /goal command at startup. If you are on an older OpenCode version where plugin config hooks do not affect command discovery, add this fallback to opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "goal": {
      "description": "Set, view, pause, resume, or clear a long-running session goal",
      "template": "$ARGUMENTS"
    }
  }
}

Install From GitHub

OpenCode uses npm package specs for plugins. Once this repository is on GitHub, install it with:

opencode plugin github:carles-grafana/opencode-goal --global

Pin a tag, branch, or commit:

opencode plugin github:carles-grafana/opencode-goal#v0.1.0 --global

Install for only the current project:

opencode plugin github:carles-grafana/opencode-goal

Alternatively, clone the repository and reference the plugin file directly:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["/absolute/path/to/opencode-goal/.opencode/plugins/goal.js"],
  "command": {
    "goal": {
      "description": "Set, view, pause, resume, or clear a long-running session goal",
      "template": "$ARGUMENTS"
    }
  }
}

Usage

/goal ship the new checkout flow and verify tests pass
/goal status
/goal set clear
/goal edit ship checkout flow, update docs, and verify tests pass
/goal pause
/goal resume
/goal clear

The model can also use create_goal, get_goal, and update_goal. update_goal only accepts complete or blocked; pause/resume/clear remain user-controlled.

Use /goal set <objective> when the objective would otherwise collide with a subcommand such as clear, pause, resume, status, or show.

Notes

This is a plugin-level port. It cannot render a native OpenCode statusline indicator or native goal editor menu without OpenCode core/TUI changes.

Some goal behavior and continuation guidance is adapted from OpenAI Codex CLI. See NOTICE and THIRD_PARTY_LICENSES.md for third-party attribution and license terms.