# opencode-worktree

> **Retired — OpenCode V1 only.** No OpenCode V2 port is planned. Use [OCX 2.0.15](https://github.com/kdcokenny/ocx/releases/tag/v2.0.15) with OpenCode V1 for the legacy installation instructions below. Existing published packages, tags, and registry artifacts remain available.
>
> Use OpenCode V2’s native workspace/worktree workflows, or ordinary Git worktrees. This plugin’s lifecycle hooks, automatic terminal handoff, and OCX environment bridge are not being ported. These are workflow alternatives, not complete replacements for every custom feature. See the [official V2 migration guide](https://opencode.ai/v2/docs/migrate-v1) and [V2 terminal settings](https://opencode.ai/v2/docs/cli/config).

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

An [OpenCode](https://github.com/sst/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](https://www.cmux.dev/)** 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

```mermaid
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

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

If you don't have OCX installed, install it from the [OCX repository](https://github.com/kdcokenny/ocx).

**Optional:** Install `kdco-workspace` for the full experience—it bundles worktrees with background agents, planning tools, and notifications:

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

## 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

```yaml
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

```yaml
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

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.

```jsonc
{
  "$schema": "https://registry.kdco.dev/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": []
  }
}
```

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:**
```jsonc
{
  "sync": {
    "copyFiles": [".env", ".env.local"],
    "symlinkDirs": ["node_modules"]
  },
  "hooks": {
    "postCreate": ["pnpm install"]
  }
}
```

**Docker-based project:**
```jsonc
{
  "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

Copy [`src/`](./src) to `.opencode/plugin/`. You lose OCX's dependency management and automatic updates.

**Requirements:**
- Manually install `jsonc-parser`
- Manual updates via re-copying

## Part of the OCX Ecosystem

From the [KDCO Registry](https://github.com/kdcokenny/ocx/tree/e79df6f/workers/kdco-registry). Combine with:

- [opencode-workspace](https://github.com/kdcokenny/opencode-workspace) - Structured planning with rule injection
- [opencode-background-agents](https://github.com/kdcokenny/opencode-background-agents) - Async delegation with persistent outputs
- [opencode-notify](https://github.com/kdcokenny/opencode-notify) - Native OS notifications

## Acknowledgments

Inspired by [opencode-worktree-session](https://github.com/felixAnhalt/opencode-worktree-session) by Felix Anhalt.

## Maintenance

This V1 code is retired. Source synchronization and active maintenance have ended. Repository history and existing releases remain available for reference and forks.

## Disclaimer

This project is not built by the OpenCode team and is not affiliated with [OpenCode](https://github.com/sst/opencode) in any way.

## License

MIT