opencode-worktree: Automated Git Worktrees for OpenCode V1

The Friction opencode-worktree Was Built to Remove

Git worktrees let you keep multiple branches checked out at the same time, each in its own directory. That is useful for AI-driven development, where an agent may need to experiment on a branch without touching the main working tree. The problem is setup friction. To use a worktree manually, you create it with `git worktree add`, open a terminal, navigate to the new directory, and start OpenCode. Four steps, each requiring human input before the agent can proceed.

OpenCode Desktop provides a GUI for worktrees, but it ties the workflow to the desktop application and offers less automation. Neither approach lets an AI agent manage the full worktree lifecycle on its own without intervention.

opencode-worktree targeted CLI-first developers running OpenCode for agentic development. It registered two tools with the OpenCode agent: `worktree_create` and `worktree_delete`. When the agent called either tool, the plugin handled everything, including terminal spawning and cleanup, without requiring a human to step in. The README describes the difference between manual worktrees and this plugin as the difference between having a tool and having a workflow.

The plugin also pairs with cmux for agentic workflows. The README describes cmux as providing native workspace management and programmatic control that fits naturally into automated development workflows, with tmux supported as an alternative for those who prefer a traditional multiplexer setup.

The Worktree Lifecycle: From Branch Name to Running Terminal

The plugin adds two tools to the OpenCode agent runtime.

`worktree_create` accepts a branch name and an optional base branch. When called, it creates a git worktree under `~/.local/share/opencode/worktree/<project-id>/<branch>/`, outside the repository directory. Keeping worktrees outside the repo prevents the main directory from accumulating extra checkout folders during parallel work. The plugin then syncs files according to the project configuration, runs post-create hooks (the README gives `pnpm install` as an example), and opens a new terminal with OpenCode already running inside.

worktree_create:
  branch: "feature/dark-mode"
  baseBranch: "main"

`worktree_delete` accepts a reason string. It runs pre-delete hooks first (the README gives `docker compose down` as an example), commits all pending changes with an automatic snapshot message, removes the worktree with `--force`, and clears session state. The agent does not need to remember to commit before deleting; the plugin does it.

worktree_delete:
  reason: "Feature complete, merging to main"

This lifecycle covers the common pattern in agentic development: create an isolated environment, do work, then dispose of it cleanly. The snapshot commit on deletion preserves work that might otherwise be lost when a worktree is removed.

Installing opencode-worktree with OCX

The plugin installs through OCX, the OpenCode extension manager. With OCX installed and available:

ocx add kdco/worktree --from https://registry.kdco.dev

This command fetches the plugin from the kdco registry. If OCX is not already installed, the README points to the OCX repository at github.com/kdcokenny/ocx for setup steps, noting that version 2.0.15 is the relevant release for OpenCode V1.

An optional bundle called `kdco-workspace` extends the installation with background agents, planning tools, and notifications alongside the worktree functionality:

ocx add kdco/workspace --from https://registry.kdco.dev

These commands apply only to OpenCode V1. The repository is archived, but the README notes that existing published packages, tags, and registry artifacts remain available. No new versions will be published.

There is no installation path that bypasses OCX. If your environment does not support OCX, or if the kdco registry becomes unreachable, the plugin cannot be installed. This is a real dependency to consider for anyone planning to adopt it.

Terminal Detection Priority: cmux, tmux, and Platform Fallbacks

The plugin selects a terminal through a fixed priority chain rather than requiring manual configuration.

First, tmux takes priority when the shell is already inside a tmux session. New worktrees open as tmux windows rather than launching separate terminal applications, which keeps everything inside the existing multiplexer.

Second, cmux is the next candidate. The README marks it as the recommended multiplexer for new agentic workflows. The plugin activates cmux when `CMUX_WORKSPACE_ID` is set in the environment, or when both `CMUX_SOCKET_PATH` and `CMUX_SOCKET_MODE=allowAll` are present. Each worktree creates a new cmux workspace. The plugin never reuses the current workspace. When cmux context is unavailable, it falls back to the next option.

Third, WSL environments use Windows Terminal via `wt.exe` interop.

Fourth, environment variable inspection reads `TERM_PROGRAM`, `KITTY_WINDOW_ID`, `GHOSTTY_RESOURCES_DIR`, and similar signals to identify the running terminal application.

Fifth, system defaults apply as a last resort: Terminal.app on macOS, xterm on Linux, and cmd.exe on Windows.

On macOS the plugin covers Ghostty, iTerm2, Kitty, WezTerm, Alacritty, Warp, and Terminal.app. On Linux it also supports Foot, GNOME Terminal, Konsole, XFCE4 Terminal, and xterm. Windows Terminal (wt.exe) serves as the primary Windows option with cmd.exe as a fallback.

The detection is automatic and works without configuration for most setups. The only case that needs explicit environment variables is cmux with socket control enabled, which requires both `CMUX_SOCKET_PATH` and `CMUX_SOCKET_MODE=allowAll`.

Configuration Through .opencode/worktree.jsonc

The plugin reads `.opencode/worktree.jsonc` in the project root for per-project settings, including file synchronization rules and lifecycle hooks.

The precedence logic has a specific rule for default-value files. If the project config holds only unchanged default values, including files generated by older plugin versions that were never edited, the plugin treats the file as a placeholder and reads `~/.config/opencode/worktree.jsonc` instead. A manually created project config, even one that contains only default values, always takes precedence over the global config. The two files are never merged.

When neither file exists, the plugin creates `.opencode/worktree.jsonc` with default values. The README states that it does not create a project config when a global config already exists.

This design means a developer who wants per-project customization must either edit the generated project file (which removes the default-placeholder status) or create a fresh project config from scratch. Using a file that is still at default values and expecting it to override the global config is a common mistake to watch for.

Retirement and the Migration Path to OpenCode V2

The repository was archived; the last push was on 2026-09-16. The README is explicit: the plugin is retired, covers OpenCode V1 only, and no port to V2 is planned.

The README names three specific capabilities that V2 does not replicate from this plugin: lifecycle hooks, automatic terminal handoff, and the OCX environment bridge. OpenCode V2's native workspace and worktree workflows replace the basic branch isolation functionality, but not those specific automation points. Teams that relied on post-create hooks for dependency installation or pre-delete hooks for container teardown will need to reproduce that logic in their own workflows.

For OpenCode V2 migration, the README points to the official guide at opencode.ai/v2/docs/migrate-v1 and the V2 terminal settings at opencode.ai/v2/docs/cli/config.

For V1 users who want worktrees without the plugin dependency, the manual approach remains an option. Running `git worktree add` creates the checkout, and OpenCode can be started in that directory manually. This removes the dependency on OCX and the kdco registry entirely, at the cost of the terminal spawning and auto-commit automation the plugin provided.

OpenCode Desktop is a third option for those who prefer a visual interface, though the README notes it ties the workflow to the GUI application. The plugin's value was specifically in letting the AI agent handle everything from the command line without human steps between creation and work.

Editorial conclusion

Engineers on OpenCode V1 who use OCX and want AI-managed worktrees can run the archived plugin as long as OpenCode V1 remains available. Anyone on OpenCode V2 should use the native workspace and worktree features. Before adding the plugin, verify that OCX still resolves the kdco registry at https://registry.kdco.dev, since the infrastructure may not receive ongoing maintenance.

Frequently asked questions

Official sources

1. Issues
2. kdcokenny/opencode-worktree on GitHub
3. License: MIT
4. README