Forge worktree loops run in native OpenCode worktrees and locations: each loop gets its own worktree directory, registered in the project's worktree inventory, and the sidebar lists the project's active loops.
See also: Loop System, Architecture, Common Issues.
Worktrees and locations are first-class in OpenCode 2.x, so there is no experimental runtime toggle, no environment variable, and no version floor. The only prerequisite is the repository requirement below.
All worktree-based execution paths require a git repository with at least one root commit: execute-plan (Loop mode), TUI Loop execution dialog launches, and the launch of a goal chunk all check for the root commit before creating worktrees or sessions. If OpenCode started before the initial commit, it resolves the project as global; create the commit, restart OpenCode, and retry.
When a worktree loop starts, Forge:
- Creates the git worktree through its own adapter (
type: "forge",branch: null,extra: { loopName, projectDirectory, workspaceCreatedAt }), including orphaned-branch reuse, worktree config, and sandbox provisioning - Persists the worktree metadata in
<worktree>/.forge/workspace.json— git-excluded and removed with the worktree - Publishes the worktree into the V2 project inventory with
ctx.worktree.refresh - Creates the loop session directly at
location.directory = <worktree>, so the session starts in the worktree location - Moves a session into the worktree with
session.movewhen a later path still needs it
The adapter's remove hook commits in-flight changes (when teardown context allows), stops the sandbox container if any, and removes the worktree directory unless the loop is restartable. Branches are preserved for later restart or merge. Workspaces are listed, reported, and removed from the persisted metadata; a record whose directory is gone is pruned.
A loop name is reserved before any side effects (src/loop/name-uniqueness.ts): a new loop start never reuses a name still referenced by a goal chunk (goal_chunks.loop_name) or whose forge/<slug> branch still exists, taking a -N suffix instead. A restart is exempt — it reuses the loop's own name and branch.
Forge deliberately does not register a worktree.transform strategy: that would silently become the default for every worktree of the user. The built-in git strategy is also rejected because its --detach add bypasses Forge's branch, orphan, config, and sandbox handling.
When a loop carries an explicit base ref — as every goal chunk after the first does, stacked on the previous chunk's branch tip — the adapter branches the worktree from that exact commit (git worktree add <dir> -b <branch> <baseRef>) instead of the project HEAD. In this mode it refuses to reuse an existing branch: if forge/<loop> already exists it throws rather than basing the new chunk on the wrong commit. The base ref is carried on the workspace extra.baseRef field.
A goal's next-chunk planning runs in a plain detached checkout at <dataDir>/worktrees/.goal-plan-<goalId>-<chunkIndex> (git worktree add --detach <dir> <commit>), not a Forge workspace. The leading dot keeps it from colliding with a loop worktree slug, and a Forge workspace with no matching loop row would be reclaimed by the stale-workspace sweep after its 5-minute grace window. The checkout is removed once the plan is captured or the goal is paused or cancelled.
If initial worktree creation fails at startup — API mismatch or a network error — the loop aborts before creating the first loop session. If a worktree disappears after a loop is already running, Forge attempts to re-provision or detach it and continue where possible.
Loops are launched from the execution dialog (or the execute-plan tool); each loop runs in its worktree directory, and the sidebar lists active loops.