opencode-worktree

Git worktree plugin for opencode. Creates isolated git worktrees with automatic terminal spawning — so AI agents can work on multiple branches in parallel without interfering with each other.

Note: This is a copy of kdcokenny/opencode-worktree repackaged as a pure npm package, since the original is only installable via ocx add which is no longer available.

Installation

bun install -g github:ykaratkou/opencode-worktree

Then add it to your opencode.json:

{
  "plugins": ["@ykaratkou/opencode-worktree"]
}

What it does

When an AI agent calls worktree_create:

1. Creates a git worktree at ~/.local/share/opencode/worktree/{projectId}/{branch}
2. Copies/symlinks files from main worktree (configurable)
3. Forks the current session (with plan and delegations)
4. Opens a new terminal with OpenCode running in the worktree

When the agent calls worktree_delete:

1. Runs pre-delete hooks
2. Commits all changes with a snapshot message
3. Removes the git worktree
4. Cleans up the session

Tools provided

worktree_create

branch: string       # Branch name (e.g., "feature/dark-mode")
baseBranch?: string  # Base branch to create from (defaults to HEAD)

worktree_delete

reason: string  # Why the worktree is being deleted

Configuration

On first use, a config file is auto-created at .opencode/worktree.jsonc:

{
  // Custom base path for worktree storage (supports ~)
  // "worktreePath": "~/my-worktrees",

  "sync": {
    // Files to copy from main worktree
    // "copyFiles": [".env", ".env.local"],

    // Directories to symlink (saves disk space)
    // "symlinkDirs": ["node_modules"],

    "copyFiles": [],
    "symlinkDirs": [],
    "exclude": []
  },

  "hooks": {
    // Commands run after worktree creation
    // "postCreate": ["pnpm install"],

    // Commands run before worktree deletion
    // "preDelete": ["docker compose down"],

    "postCreate": [],
    "preDelete": []
  }
}

Terminal support

Automatically detects and uses:

• tmux (highest priority when inside a tmux session)
• cmux (agentic workflow multiplexer)
• macOS: Ghostty, iTerm2, Kitty, Alacritty, Warp, Terminal.app
• Linux: Kitty, WezTerm, Alacritty, Ghostty, Warp, Foot, GNOME Terminal, Konsole, XFCE4, xterm
• Windows: Windows Terminal (wt.exe), cmd.exe

Requirements

• opencode with Bun runtime
• git

License

MIT