Worktree Plugin

Overview

An OpenCode plugin that creates isolated git worktrees where each worktree automatically opens its own terminal with OpenCode running inside. No manual setup, no context switching, no cleanup work.

Why This Exists

Manual worktrees require setup: create the worktree, open a terminal, navigate to it, start OpenCode. This plugin eliminates that friction. When the AI calls worktree_create, your terminal spawns automatically, OpenCode is already running, and files are synchronized. When it calls worktree_delete, changes commit automatically and the worktree cleans itself up. Works great standalone, but pairs especially well with cmux for agentic workflows. cmux provides native workspace management and programmatic control designed for automated development workflows. Each worktree launch opens a new cmux workspace (no current-workspace reuse). tmux is also supported for traditional multiplexer setups, and remains runtime-priority when already inside a tmux session.

When to Use This

Approach	Best For	Tradeoffs
Manual git worktree	One-off experiments, full control	Manual setup, no auto-cleanup
OpenCode Desktop UI	Visual workflow, integrated experience	Tied to desktop app
This plugin	AI-driven workflows, automation, CLI-first users	Adds plugin dependency

Installation

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

Or install the full Workspace bundle:

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

How It Works

Create — AI calls worktree_create("feature/dark-mode")
Terminal spawns — New window opens with OpenCode at the worktree path
Work — AI experiments in complete isolation
Delete — AI calls worktree_delete("reason")
Cleanup — Changes commit automatically, git worktree removed

Worktrees are stored in ~/.local/share/opencode/worktree/<project-id>/<branch>/ outside your repository.

Tools

Tool	Purpose
`worktree_create(branch, baseBranch?)`	Create a git worktree with automatic terminal spawning
`worktree_delete(reason)`	Delete worktree with auto-commit before removal

Platform Support

Platform	Terminals Supported
macOS	Ghostty, iTerm2, Kitty, WezTerm, Alacritty, Warp, Terminal.app
Linux	Kitty, WezTerm, Alacritty, Ghostty, Foot, GNOME Terminal, Konsole, xterm
Windows	Windows Terminal (wt.exe), cmd.exe fallback
cmux	Uses native cmux workflow when `CMUX_WORKSPACE_ID`/cmux control env is available; each worktree launch opens a new cmux workspace, then falls back safely
tmux	Creates new tmux window (supported on all platforms)
WSL	Windows Terminal via wt.exe interop

Configuration

The plugin reads .opencode/worktree.jsonc first. A project file created by the plugin is treated as a placeholder when it still contains only default values, so the plugin reads ~/.config/opencode/worktree.jsonc when that file exists. A manually created project config always takes precedence, including one with only default values. Unchanged default files generated by older plugin versions are also recognized. The two files are not merged. If neither config file exists, the plugin creates .opencode/worktree.jsonc with default values. The plugin does not create a project config when the global config exists.

{
  "$schema": "https://registry.kdco.dev/schemas/worktree.json",
  "sync": {
    "copyFiles": [],
    "symlinkDirs": [],
    "exclude": []
  },
  "hooks": {
    "postCreate": [],
    "preDelete": []
  }
}

For settings shared across projects, create ~/.config/opencode/worktree.jsonc. It is used when no project config exists or when the project file is an auto-generated default that still contains only default values.

Common Configurations

Node.js project:

{
  "sync": {
    "copyFiles": [".env", ".env.local"],
    "symlinkDirs": ["node_modules"]
  },
  "hooks": {
    "postCreate": ["pnpm install"]
  }
}

Docker-based project:

{
  "sync": {
    "copyFiles": [".env"]
  },
  "hooks": {
    "postCreate": ["docker compose up -d"],
    "preDelete": ["docker compose down"]
  }
}

Getting Started

Profiles

CLI

Registries

Reference

Guides

Integrations

Enterprise

Security

Overview

Why This Exists

When to Use This

Installation

How It Works

Tools

Platform Support

Configuration

Common Configurations

See Also

​Overview

​Why This Exists

​When to Use This

​Installation

​How It Works

​Tools

​Platform Support

​Configuration

​Common Configurations

​See Also

Overview

Why This Exists

When to Use This

Installation

How It Works

Tools

Platform Support

Configuration

Common Configurations

See Also