opencode-worktree

Git worktrees that spawn their own terminal. Zero-friction isolation for AI-driven development.

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

You already know you can create git worktrees manually. Or use OpenCode Desktop's UI. So why this plugin?

Manual worktrees require setup: create the worktree, open a terminal, navigate to it, start OpenCode. OpenCode Desktop gives you worktrees, but locks you into the GUI workflow. Each approach has friction.

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. It's the difference between having a tool and having a workflow.

Works great standalone, but pairs especially well with tmux for seamless window management. When running inside tmux, worktrees spawn as new windows instead of separate terminal apps—keeping everything organized in a single terminal session with zero external window overhead.

When to Use This

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

If you prefer manual control or work exclusively in OpenCode Desktop, you may not need this. But if you want AI agents to seamlessly create and manage isolated development sessions—complete with automatic terminal spawning and state cleanup—this is what you're looking for.

How It Works

flowchart LR
    A[Create Worktree] --> B{Terminal Spawns}
    B --> C[OpenCode Running]
    C --> D[Work in Isolation]
    D --> E[Delete Worktree]
    E --> F{Auto-commit & Cleanup}
    F --> G[Session Ends]

1. Create - AI calls worktree_create("feature/dark-mode")
2. Terminal spawns - New window opens with OpenCode at ~/.local/share/opencode/worktree/<project-id>/feature/dark-mode
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.

Installation

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

If you don't have OCX installed, install it from the OCX repository.

Optional: Install kdco-workspace for the full experience—it bundles worktrees with...