Playbooks · Coding tasks
OpenCode 2.2.6: scripted sessions, clean trees
Written November 8, 2026
OpenCode 2.2.6 runs scripted sessions in fresh worktrees with one shared MCP connection. What it writes, and what to check after a run.
What 2.2.6 adds
OpenCode 2.2.6, released November 6, 2026, is a scripting release: three changes aimed at running OpenCode from scripts and CI instead of from the terminal. The release notes list them under shared MCP connections, scripted runs in worktrees, and automatically archived runs.
- Shared MCP connections. Turn on pooling for an MCP server —
pool: truein its configuration — to share one connection across projects with the same setup. Fewer processes, faster starts. Pooling is opt-in per server. - Scripted runs in worktrees. Run
opencode run -wto start the session in a new git worktree, or--worktree=<name>to name it. The session works in the worktree, so the main checkout stays clean. - Automatically archived runs. Add
--archivedtoopencode runto create the session already archived, so scripted and CI sessions stay out of the inbox, home, and session lists. Archived sessions are also hidden from the TUI session list and skipped by--continue.
The change that can hang your CI
The same release changes how opencode run waits. It now waits for the background shell commands, subagents, and image jobs its prompt started, then lets the model respond to their results before it exits. While it waits, it prints waiting for N background job(s). There is no time limit: a job that never exits, such as a dev server or file watcher, keeps the run open until you press Ctrl+C or send SIGTERM. The release notes say so plainly — set a timeout on CI jobs.
Related to that: SIGTERM now cancels the session and its background jobs and exits with code 143. A CI job that kills the run with SIGTERM gets a clean 143 rather than a hanging process, provided the timeout is actually set. Without the timeout, there is nothing to send the signal.
What to check after a scripted run
- What landed in the worktree.
--worktreecannot be combined with--continueor--session, so each scripted run starts fresh. List the worktree after the run and diff it against the base branch before merging anything back. - What the inbox shows. A run with
--archivedshould not appear in the inbox or the session lists. If it does, the flag did not take — check that the run actually used 2.2.6 and that the flag was on theruncommand, not on a wrapper. - What the shared MCP connection served. Pooling shares one connection across projects with the same setup. If two projects configure the same server differently, they do not share — check that the setups match before assuming one connection is serving both.
- Whether anything is still running. The no-timeout wait means a scripted run can outlive the CI step that started it. Check for leftover dev servers or watchers after the run exits, and confirm the CI timeout fired if the run was killed.
What this release does not do
- It does not isolate the worktree's environment. A fresh git worktree is a clean tree, not a sandbox. A scripted session in a worktree can still run shell commands, write outside the tree, and reach the network, subject to whatever permissions the session has.
- It does not clean up after itself. The release notes describe where sessions start and where they are listed. They say nothing about removing worktrees or archived sessions afterwards — that cleanup is yours to schedule.
- Pooling does not merge different setups. One connection is shared only across projects with the same setup. Different server configurations still mean different connections.
Limits
- This page reads OpenCode's changelog. It reports no scripted session run here — no throwaway repository, no worktree, no shared MCP connection — so it says nothing firsthand about what a scripted run writes, what the inbox shows afterwards, or what the shared connection serves.
- The behaviour claims on this page are the changelog's. The changelog walks the flags; only a run shows what they write in a particular setup.
- The release date is November 6, 2026, per the changelog. Some summaries dated the release November 7; the changelog is the dated record.
Related playbooks
- Copilot in JetBrains Air: follow agent sessions
- Move OpenCode 1.x to 2.0 without losing config
- OpenCode 1 offers the upgrade to OpenCode 2
- OpenCode 2.2.7: Copilot Auto and breaking changes
Sources
Back to: Coding playbooks hub · Also: Use Claude Code login inside OpenCode · Manage Git worktrees for parallel AI agents with Worktrunk · Run parallel subagents in Claude Code