OpenCode Forge

Loops, plans, sandboxing, and code review for OpenCode AI agents

Quick Start

pnpm add opencode-forge

Forge requires OpenCode 2.x (engines.opencode is >=2.0.14) and is verified on OpenCode 2.2.2; see OpenCode Compatibility.

Install

Add to your opencode.json to enable Forge's server-side hooks, tools, and agents:

{
  "plugins": ["opencode-forge@latest"]
}

OpenCode 2 loads the plugin's TUI surface from the same entry, so no separate terminal config is needed. A config-directory install writes a cli.json entry instead — see Plugin-directory install.

Plugin-directory install

Instead of editing the plugin arrays by hand, the installer can wire the plugin into opencode's config directory:

bunx opencode-forge --link        # point the server shim and cli.json at the current build
bunx opencode-forge --vendor      # self-contained copy (portable)

From a source checkout, use pnpm run setup --link or pnpm run setup --vendor. Both modes register the TUI in cli.json's plugins array. --link also writes a server shim <configDir>/plugin/opencode-forge.js; --vendor instead places the self-contained package at <configDir>/plugin/opencode-forge, which OpenCode discovers directly, so it writes no shim and removes a stale one. In a non-interactive shell the flags still require -y, -f, or -k.

	--link	--vendor
Picks up a rebuild	Yes — the shim and cli.json point at the live dist directory	No — re-run after upgrade
Portable to another machine	No — absolute path to this checkout	Yes
Payload in config dir	Shim file and cli.json entry	Full copy (~6.5 MB)
Needs re-run after upgrade	No	Yes

Loop worktrees use OpenCode 2's native worktree and location model: no environment variable and no version floor. See Workspace Integration.

Upgrading

Migration 157 drops the goals and goal_chunks tables: goals and the architect-auto agent are removed. On the version you are upgrading from, cancel running goals with goal-cancel before upgrading, so no chunk loop is left mid-flight. A chunk loop that is still running when you restart the OpenCode server into the new version is not resumed — plugin boot never recovers a loop persisted before the process started — so it keeps its running status until you restart it with loop-status name=<loop> restart=true force=true (a running loop requires force), or cancel it with loop-cancel. Forge does not remove a leftover .goal-plan-* planning checkout under <dataDir>/worktrees; remove it from the project repository with git worktree remove --force <dir> (or delete the directory and run git worktree prune), and delete any kept chunk planner session in OpenCode.

What Forge Adds

Forge ships two plugin entrypoints plus standalone management surfaces:

• Server plugin — enabled through the plugins array in opencode.json. Provides the core hooks, tools, agents, plan storage, loop orchestration, review persistence, and sandbox support.
• TUI plugin — the loop sidebar, the unified execution dialog (launch, restart, and per-loop launch settings), and the per-session host-sandbox and auto-approve toggles. It loads from the server plugin entry, or from the cli.json plugins array, and reads and changes Forge state over the server's RPC surface, so it also works attached to a remote OpenCode server. It also hosts the Dashboard: a project list with search, plus Loops, Findings and Plans sections and per-loop detail.
• Installer CLI — installs/upgrades bundled prompts and skills, and registers the plugin in opencode's config directory (--link/--vendor/--unlink).
• Dashboard — a TUI observability surface opened from the command palette (Open dashboard) or a keybind, covering every project's loops, findings, and plans.

For a quick tour of the loop itself, see Loop Flow below.

Limitations

The server side — loops, plans, review findings, tools, agents, commands, permissions, sandboxing, and event handling — all run on OpenCode 2.x. These are the current constraints:

• Subtask commands — review and review-plan run inline in the invoking session instead of spawning a subtask. Every Forge command runs its turn as the command's agent, then Forge switches the session back to the agent it had before.
• Session transcripts — OpenCode 2 exposes a session's history only from its latest compaction onward. Loop usage totals stay exact because Forge reconciles them against the session's cumulative cost and tokens, attributing the pre-compaction share to the session's model.
• TUI/server version — the TUI reads and changes Forge state over the server's RPC surface, so it must run the same Forge version as the server plugin. On a mismatch it warns, and a restart requested by a TUI older than the RPC is not handled; restart the OpenCode server after upgrading.

Features

• Plans — architect authors validated plans directly into SQL storage with plan-write/plan-edit
• Execution — approved-plan launch paths in dedicated worktree sessions
• Loops — iterative coding/auditing with an isolated git worktree and optional msb sandbox
• Review Findings — persistent, loop-scoped review findings across loop sessions
• TUI — loop sidebar, a unified execution dialog with model, variant, and per-loop launch settings, and per-session host-sandbox and auto-approve toggles
• Dashboard — a TUI repo shell for loops, findings, and plans, with live loop state, a text state-machine view, and stored plan diffs

Documentation

• Agents and Slash Commands — the bundled code, architect, and auditor agents, hidden loop agents, and every slash command.
• Planning and Execution Workflow — how the architect authors plans, the three execution modes, and variants.
• Tools Reference — full arguments, section-scoping behavior, restart options, and sandbox shell details.
• Loop System — phases, section lifecycle, review findings, session rotation, stall detection, model configuration, and termination.
• TUI Plugin — sidebar, palette commands, the execution dialog, per-loop launch settings, per-session auto-approve, model selection, and setup.
• Dashboard — opening the TUI dashboard, its views and key bindings, live updates, and plan deletion.
• Workspace Integration — OpenCode workspace registration, requirements, and failure behavior.
• Sandbox — host requirements, image building and loading, network access, secrets, bind mounts, and resource defaults.
• Configuration Reference — every option in forge-config.jsonc, plus the installer and bundled-asset sync.
• OpenCode Compatibility — the verified OpenCode version, the supported floor, and the probes behind the verdict.
• Architecture — plugin architecture, module layout, hooks, storage, and data flow.
• Modules — the source tree and each module's public surface.
• Common Issues — worktree launch failures and workspace prerequisites.

Screenshots

The unified execution dialog — plan, execution model and variant, and auditor model and variant selection:

The rest of the dialog — loop name, the per-loop settings summary, and the launch modes:

The per-loop settings submenu — max iterations and sandbox resource overrides:

Loop Flow

The diagram below shows the overall flow of the Forge loop system — from loop trigger and provisioning through coding/auditing, section advancement, and the optional post-action phase. See Loop System for the full lifecycle. Source: diagrams/loop-flow.mmd.

Development

Install pnpm and Bun; build and setup scripts require Bun. Use pnpm for dependencies.

pnpm install --frozen-lockfile
pnpm build && pnpm typecheck && pnpm lint && pnpm test

License

MIT