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 cmux for agentic workflows. cmux provides native workspace management and programmatic control that fits naturally into automated development workflows. tmux is also supported if you prefer a traditional multiplexer setup.

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

在项目根目录的 opencode.json 中加入：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@devcxl/opencode-worktree"]
}

前置条件：OpenCode 所使用的 shell 必须能直接执行 node。

Usage

The plugin adds two tools:

| Tool | Purpose | |------|---------| | worktree_create(branch, baseBranch?) | Create a new git worktree for isolated development. A new terminal spawns with OpenCode ready. | | worktree_delete(reason) | Delete the current worktree. Changes commit automatically before removal. |

Creating a Worktree

worktree_create:
  branch: "feature/dark-mode"
  baseBranch: "main"  # optional, defaults to HEAD

When called, this:

1. Creates git worktree at ~/.local/share/opencode/worktree/<project-id>/feature/dark-mode
2. Syncs files based on .opencode/worktree.jsonc config
3. Runs post-create hooks (e.g., pnpm install)
4. Opens a new terminal with OpenCode running

Deleting a Worktree

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

When called, this:

1. Runs pre-delete hooks (e.g., docker compose down)
2. Commits all changes with snapshot message
3. Removes git worktree with --force
4. Cleans up session state

Platform Support

The plugin detects your terminal automatically:

| Platform | Terminals Supported | |----------|---------------------| | macOS | Ghostty, iTerm2, Kitty, WezTerm, Alacritty, Warp, Terminal.app | | Linux | Kitty, WezTerm, Alacritty, Ghostty, Foot, GNOME Terminal, Konsole, XFCE4 Terminal, xterm | | Windows | Windows Terminal (wt.exe), cmd.exe fallback | | cmux | Uses native cmux workflow when CMUX_WORKSPACE_ID is present or socket control is explicitly enabled (CMUX_SOCKET_PATH + CMUX_SOCKET_MODE=allowAll); each worktree launch opens a new cmux workspace and falls back safely when unavailable | | tmux | Creates new tmux window (supported on all platforms) | | WSL | Windows Terminal via wt.exe interop |

Detection Priority

1. tmux - Runtime priority on all platforms when already inside tmux. Creates new tmux windows instead of spawning separate terminal applications.
2. cmux - Recommended for new agentic workflows. Uses native cmux launch flow when available via CMUX_WORKSPACE_ID or explicit socket control (CMUX_SOCKET_PATH with CMUX_SOCKET_MODE=allowAll). Worktree launches always create a new cmux workspace (no current-workspace reuse), then fall back safely when cmux context is unavailable.
3. WSL - Uses Windows Terminal for Linux subsystem
4. Environment vars - Checks TERM_PROGRAM, KITTY_WINDOW_ID, GHOSTTY_RESOURCES_DIR, etc.
5. Fallback - System defaults (Terminal.app, xterm, cmd.exe)

Configuration

Auto-creates .opencode/worktree.jsonc on first use:

{
  "$schema": "https://github.com/devcxl/opencode-worktree/raw/main/schemas/worktree.json",

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

    // Directories to symlink
    "symlinkDirs": [],

    // Patterns to exclude
    "exclude": []
  },

  "hooks": {
    // Run after creation
    "postCreate": [],

    // Run before deletion
    "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"]
  }
}

FAQ

Why not just use git worktree manually?

Manual worktrees require manual setup: git worktree add, opening a terminal, navigating to it, starting OpenCode. Each step is friction. This plugin gives you a single command that handles everything end-to-end, complete with automatic file synchronization and lifecycle hooks.

Does this work with OpenCode Desktop?

Worktrees created with this plugin work fine in OpenCode Desktop, but you lose the automatic terminal spawning. The plugin's value is in CLI-first workflows and AI automation—if you prefer Desktop exclusively, you may not need this.

What happens if I forget to delete the worktree?

Changes remain in ~/.local/share/opencode/worktree/<project-id>/<branch>. The branch exists in git. You can manually check out or delete it later. The plugin doesn't force cleanup—it's just the convenient default path.

Can I have multiple worktrees simultaneously?

Yes. Each gets its own terminal and OpenCode session. They're fully independent.

Does this break my existing git workflow?

No. It uses standard git worktrees. git worktree list shows them. Branches merge normally.

Why spawn a new terminal instead of reusing the current one?

Isolation. You can close the worktree session without affecting your main workflow. If the AI breaks something, your original terminal remains untouched.

Limitations

Security

• Branch names validated against git ref rules and shell metacharacters
• File sync paths validated to prevent directory traversal
• Hook commands run with user privileges in worktree directory

Terminal Spawning

• Ghostty on macOS uses inline commands to avoid permission dialogs
• Kitty tab support requires allow_remote_control config (falls back to window)
• Some terminals don't support tabs; opens new OS window instead

Manual Installation

Disclaimer

This project is not built by the OpenCode team and is not affiliated with OpenCode in any way.

License

MIT