Skip to main content

​
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

ApproachBest ForTradeoffs
Manual git worktreeOne-off experiments, full controlManual setup, no auto-cleanup
OpenCode Desktop UIVisual workflow, integrated experienceTied to desktop app
This pluginAI-driven workflows, automation, CLI-first usersAdds 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

  1. Create — AI calls worktree_create("feature/dark-mode")
  2. Terminal spawns — New window opens with OpenCode at the worktree path
  3. Work — AI experiments in complete isolation
  4. Delete — AI calls worktree_delete("reason")
  5. Cleanup — Changes commit automatically, git worktree removed
Worktrees are stored in ~/.local/share/opencode/worktree/<project-id>/<branch>/ outside your repository.

​
Tools

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

​
Platform Support

PlatformTerminals Supported
macOSGhostty, iTerm2, Kitty, WezTerm, Alacritty, Warp, Terminal.app
LinuxKitty, WezTerm, Alacritty, Ghostty, Foot, GNOME Terminal, Konsole, xterm
WindowsWindows Terminal (wt.exe), cmd.exe fallback
cmuxUses native cmux workflow when CMUX_WORKSPACE_ID/cmux control env is available; each worktree launch opens a new cmux workspace, then falls back safely
tmuxCreates new tmux window (supported on all platforms)
WSLWindows Terminal via wt.exe interop

​
Configuration

Auto-creates .opencode/worktree.jsonc on first use: 
{
  "$schema": "https://registry.kdco.dev/schemas/worktree.json",
  "sync": {
    "copyFiles": [],
    "symlinkDirs": [],
    "exclude": []
  },
  "hooks": {
    "postCreate": [],
    "preDelete": []
  }
}

​
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"]
  }
}

​
See Also