Loops, plans, sandboxing, and code review for OpenCode AI agents
pnpm add opencode-forgeForge requires OpenCode 2.x (engines.opencode is >=2.0.14).
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.
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 write a server shim <configDir>/plugin/opencode-forge.js (OpenCode loads the server plugin from *.js files there) and register the TUI in cli.json's plugins array. 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.
Forge ships two plugin entrypoints plus standalone management surfaces:
- Server plugin — enabled through the
pluginsarray inopencode.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.jsonpluginsarray, and reads and changes Forge state over the server's RPC surface, so it also works attached to a remote OpenCode server. - Installer CLI — installs/upgrades bundled prompts and skills, and registers the plugin in opencode's config directory (
--link/--vendor/--unlink). - Dashboard — an observability interface launchable from the TUI command palette (
Open web dashboard) or viapnpm dashboard(source checkouts only).
For a quick tour of the loop itself, see Loop Flow below.
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 —
reviewandreview-planrun 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.
- Plans — architect authors validated plans directly into SQL storage with
plan-write/plan-edit - Execution — approved-plan launch paths plus direct
/execute-goalloops in dedicated worktree sessions; grouped execution launches features from a PRD as parallel loops - 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 repo shell for loops, groups, findings, and plans, with loop state
- Agents and Slash Commands — the bundled
code,architect, andauditoragents, hidden loop agents, and every slash command. - Planning and Execution Workflow — how the architect authors plans, the three execution modes, variants, and grouped execution.
- 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 — views, hash deep links, and the HTTP API.
- 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. - 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.
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:
The diagram below shows the overall flow of the Forge loop system — from loop trigger and provisioning through coding/auditing, section advancement, the final audit, and the optional post-action phase. See Loop System for the full lifecycle. Source: diagrams/loop-flow.mmd.
pnpm build # Compile TypeScript to dist/
pnpm test # Run tests
pnpm typecheck # Type check without emittingMIT