OpenCode Goal Plugin
Adds Codex-style long-running goal mode to OpenCode so AI coding agents keep working toward one explicit objective until complete, blocked, or cleared.
- Source repo
- prevalentWare/opencode-goal-plugin
- Stars
- ★ 511
- Last updated
- 2d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 73/100 · Some gaps
At a glance
- How it runs
- Works with
- Platform-specificCodex (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer running a long refactor, migration, or code review wants the agent to keep working across idle turns toward one stated objective.
- Not a fit if
- Developers not using the OpenCode CLI; it cannot run in other agent runtimes
- Teams needing a stable release, since OpenCode 2 is beta and the V2 contract is pinned to one preview
- Users wanting cost caps out of the box, as token and duration budgets are unset by default
- Source review
- 73/100 · Some gaps
What does this agent do, and when should you use it?
OpenCode Goal Plugin is an MIT-licensed npm package (@prevalentware/opencode-goal-plugin) from prevalentWare that brings Codex-style long-running goal mode to OpenCode. It exposes /goal, /pause_goal, and /resume_goal slash commands plus agent tools such as get_goal, set_goal, and update_goal, backed by persistent per-session goal state. Goals can only be closed as complete with verified evidence or as unmet with a concrete blocker, and optional auto-continuation on session.idle is governed by token budgets, time limits, and no-progress safeguards. Plan-mode safety ensures goals created from the plan agent stay paused and auto-continue never escapes a planning session. State is stored atomically in a local goals. file, and a TUI sidebar shows status, elapsed time, usage, and the objective. It targets developers already using OpenCode, not standalone agent users.
Once installed, the plugin registers /goal <objective> (plus /goal pause, /goal resume, /goal history, /goal clear and aliases) and lets agents read and write goals through the create_goal, set_goal, update_goal, update_goal_status, update_goal_objective, get_goal, get_goal_history, list_all_goals, and clear_goal tools. update_goal closes a goal as status: complete with evidence or status: unmet with blocker. Safety states include budgetLimited, usageLimited, and paused. Auto-continuation is driven by V2 session.execution.succeeded and legacy session.idle/session.status events, bounded by max_auto_turns, default_token_budget, max_goal_duration_seconds, and max_no_progress_turns; on hitting a limit the plugin sends one wrap-up handoff prompt instead of continuing forever. State is written atomically to $XDG_DATA_HOME/opencode-goal-plugin/goals. (override via OPENCODE_GOAL_STATE_PATH), with corrupt files quarantined as goals..corrupt-<timestamp>-<uuid>. The TUI sidebar shows status, elapsed time, token usage, auto-continue count, latest checkpoint, and stop reason.
- A developer running a long refactor, migration, or code review wants the agent to keep working across idle turns toward one stated objective.
- A team requires verified evidence (files, tests, PR state) before a goal is marked done, rather than trusting the agent's claim.
- A user's long session gets summarized by OpenCode and the current goal, budget, and history must survive compaction.
- Security-conscious teams rely on Plan mode: goals created from the plan agent pause automatically and cannot self-escalate into execution.
- Remote integrations (desktop, web) discover /pause_goal and /resume_goal through OpenCode's server command catalog to control goals remotely.
- Teams want token or elapsed-time budgets on long tasks so the goal safely wraps up with a handoff when limits are hit.
How do you install or deploy this agent?
OpenCode 1 stable: run opencode plugin @prevalentware/opencode-goal-plugin (add -g for global), or add {"plugin": ["@prevalentware/opencode-goal-plugin"]} to both opencode.json and tui.json. OpenCode 2 beta (opencode2): add {"plugins": ["@prevalentware/opencode-goal-plugin"]} to opencode.json and to ~/.config/opencode/cli.json (OpenCode 2 does not read tui.json). Do not mix the two configuration formats. The npm package is @prevalentware/opencode-goal-plugin.
How do you use this agent?
In a fresh OpenCode chat, create a goal with /goal <objective>, e.g.: /goal review the frontend and translate visible English UI text to Spanish. Bare /goal reports state; /goal history shows lifecycle history and checkpoints; /goal edit updates the objective; /goal pause and /goal resume pause/resume; /goal clear (aliases: off, reset, none) archives the goal; /goal stop or /goal cancel ends it as cancelled. You can also ask the agent to call set_goal with its own formulated objective. Include scope, non-goals, and a verification path in the objective. The TUI command palette's Goal entry lets you view, refresh, pause, resume, or clear the current goal. Plugin options such as auto_continue, max_auto_turns, default_token_budget, max_goal_duration_seconds, and restricted_agents are configured in opencode.json.
What are this agent's strengths and limitations?
- Goal closure requires evidence for complete or a concrete blocker for unmet, discouraging false completion claims.
- Goal state survives session compaction and auto-continues on session.idle, eliminating repeated user prompting.
- Layered Plan-mode safety: plan-agent goals start paused, resumption is refused from Plan mode, and continuation prompts are pinned to the recorded agent, defeating prompt injection escalation.
- Fine-grained safeguards: token/duration budgets, max_auto_turns, no-progress pause, Task child-session deferral with a max_task_block_seconds ceiling.
- Atomic, owner-only-permission state file with corrupt-file quarantine and full recovery of objective, budget, history, and checkpoints.
- Deeply tied to the OpenCode ecosystem: unusable outside the OpenCode CLI, with no documented support for Claude Code, ChatGPT, or other agent runtimes.
- OpenCode 2 is beta; the plugin pins its V2 contract to preview 0.0.0-next-17055, so later previews may require a plugin update, and V2 lacks goal compaction context and child-session recovery (V1-only).
- Auto-continuation can consume extra tokens; budget options (default_token_budget, max_goal_duration_seconds) are unset by default and must be configured to cap spend.
- fsync is not F_FULLFSYNC, so sudden power loss on macOS/APFS offers no absolute durability guarantee (stated in the README).
- Beyond CI-checked tests and a documented smoke test, there is little externally auditable production evidence; stability depends on the evolving OpenCode plugin API.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| OpenCode Goal Plugin This agent | 73 · Some gaps | Agent plugin / skillFree + model costs | ★ 511 | 2d ago | TypeScript | — |
| pi ACP Adapter | 66 · Some gaps | CLIFree + model costs | ★ 742 | 19d ago | TypeScript | — |
| rpi: Rust Coding-Agent Runtime | 64 · Some gaps | CLIFree + model costs | ★ 148 | 1d ago | Rust | OpenAI API · Claude API |
| PRO-LONG | 57 · Major gaps | CLIFree | ★ 459 | 2mo ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows 0600 owner-only state file, UUID exclusive temp-file atomic writes (test-asserted), plan-agent goals paused by default, codemode:false, configurable restricted_agents. Deductions: auto_continue defaults to true (autonomous continuation on by default, though budget/pause guardrails exist), and the main sources (src/server.ts, state.ts) are absent from the evidence, so least_privilege is 2. Goals from plan mode pause and resuming is an explicit user action (2), but the agent may set_goal itself. Dependencies are version ranges plus a frozen lockfile with no audit evidence, so dependency_security is 1. State path is documented and no telemetry is evident, giving data_flow_transparency and sensitive_data_handling 2 each. External effects stay inside the OpenCode session with budget ceilings (2); corrupt-state quarantine, pause/resume, and old-file preservation give basic rollback (2). Credits explicitly name William Ricchiuti's willytop8/OpenCode-goal-plugin — full attribution (3).
Atomic-write failure paths are exceptionally well tested (sync/rename/close failures preserve the old state and clean temp files) and errors are reported honestly (graceful degradation when dir fsync is unsupported, genuine I/O errors surfaced), so failure_messages is 3. Lockfile-pinned deps with CI give dependency_availability 2. Self-consistency is clearly dented: the README claims 'Plugin release 0.1.30 and newer supports OpenCode 2' while package. says 0.1.1, and many described behaviors cannot be checked against this revision — self_consistency is 1.
The README names concrete users (long refactors/migrations/test-fixing), dual OpenCode 1/2 paths, and itemizes V2 beta limits — audience_and_scenarios 3. Boundaries are exhaustive: max_objective_chars, budgets, max_task_block_seconds, continuation trigger/suppression conditions, watchdog and budget accounting — capability_boundaries 3. Triggers are precise (V2 execution.succeeded, legacy idle, task deferral with timers, dedup, pause persisted before ack) — trigger_precision 3. Cross-platform handling (Windows rename retries for EPERM/EACCES/EBUSY, platform-specific dir fsync, honest APFS fsync caveats) is test-backed — environment_fit 3.
README is well structured (install, options, workflow, plan safety, state, development, publishing) — information_architecture 3; install notes distinguish OpenCode 1/2 with manual configs — install_notes 3. Naming: scoped package name and command_name config with pause_goal/resume_goal fallback, but the version disconnect risks instability — 2. Examples exist (/goal usage, config samples) but no FAQ/troubleshooting — 2. Known limitations are honest and specific (V2 lacks compaction context and child-session recovery; fsync limits) — 3. LICENSE file matches package. — 3. No CHANGELOG, plus the version self-consistency problem — versioning_changelog 1. SECURITY.md (5-day ack, private reporting) and automated publishing CI exist, but the publisher is unverified and only the latest version is supported — maintenance_responsibility 2.
Tool outputs are structured JSON content, the sidebar shows status/time/tokens/checkpoints, and closing requires evidence or a blocker — output_usability 2 (main sources unavailable, so not full marks). It fills a real gap (long-running goal mode in OpenCode, Codex-aligned semantics) — marginal_value 2. Budgets, wrap-up prompts, and no-progress pauses curb runaway continuation; design is sound but actual consumption is unverified without execution — cost_benefit 2.
The README makes many behavioral promises (continuation dedup, pause ordering, V2 event driving) that cannot be statically traced because the core src files are not in the evidence — claim_traceability 1. README, package., CI, SECURITY.md, and tests corroborate each other on atomic writes, tool/command registration, and recovery — cross_source_corroboration 2. The README distinguishes facts from limits (fsync is not an absolute durability guarantee; V2 is beta), though SEO-style keyword paragraphs dilute this — fact_inference_separation 2.
- Version self-consistency is questionable: the README references 0.1.30+ for OpenCode 2 support while package. says 0.1.1 — verify the published npm version against the docs before installing.
- auto_continue defaults to true: goals will auto-continue and consume model quota; set it to false or configure token/time budgets in sensitive environments.
- Publisher identity is unverified; core src files are absent from the evidence, so audit the dist artifacts and dependencies yourself before adoption.
- No dependency audit evidence is provided; run npm audit / lockfile review before integrating.
- goals. holds objectives and usage metadata in the user data directory; mind local privacy on shared hosts.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Published npm version: @prevalentware/[email protected] Validation: - Typecheck passed. - Lint passed. - Unit tests passed. - V2 lifecycle smoke passed against @opencode/[email protected]. - Minimum and host OpenTUI compatibility passed. - Package published to npm.View on GitHub ↗ -
Release notes excerpt
Published npm version: @prevalentware/[email protected] Validation: - Typecheck passed. - Lint passed. - Unit tests passed. - V2 lifecycle smoke passed against @opencode/[email protected]. - Minimum and host OpenTUI compatibility passed. - Package published to npm.View on GitHub ↗ -
Release notes excerpt
Published npm version: @prevalentware/[email protected] Validation: - Typecheck passed. - Lint passed. - Unit tests passed. - V2 lifecycle smoke passed against @opencode/[email protected]. - Minimum and host OpenTUI compatibility passed. - Package published to npm.View on GitHub ↗
FAQ
Does OpenCode have a built-in /goal command?
/init, /undo, /redo and /help, and does not document a /goal command. Goal mode comes from community plugins such as this one, which adds /goal, /pause_goal and /resume_goal modelled on Codex's goal mode.Does the goal plugin work with OpenCode 2 (v2)?
plugins in opencode.json and ~/.config/opencode/cli.json. OpenCode 2 plugin APIs are still beta, so a later preview may need a plugin update.How do I set, pause or clear a goal?
/goal <objective> to start one and bare /goal to see its state. /goal pause and /goal resume pause and resume it, and /goal clear archives it without deleting its history. A goal can close as complete only with evidence, or as unmet with a concrete blocker.