opencode-worktree: Zero-Friction Git Worktrees for AI-Driven Development

Introduction

opencode-worktree is an innovative OpenCode plugin that revolutionizes how developers interact with git worktrees. It provides a zero-friction solution for creating isolated development environments, automatically spawning dedicated terminals with OpenCode running inside. This eliminates manual setup, context switching, and cleanup, making it perfect for modern, AI-driven development workflows.

Why Use It & Benefits

Traditional git worktree management, whether manual or via OpenCode Desktop's UI, often introduces friction. Manual worktrees require multiple steps: creating the worktree, opening a terminal, navigating, and then starting OpenCode. While OpenCode Desktop offers a visual approach, it can limit automation.

opencode-worktree addresses these challenges by providing a seamless, automated workflow:

• Zero-Friction Isolation: When an AI agent calls worktree_create, a new terminal automatically spawns with OpenCode pre-loaded, and files are synchronized. For worktree_delete, changes are committed, and the worktree is cleaned up automatically.
• AI-Driven Development: It's specifically designed to integrate with AI agents, allowing them to effortlessly create and manage isolated development sessions.
• Automated Lifecycle Management: Handles the entire worktree lifecycle, from creation to cleanup, reducing developer overhead.
• Terminal Automation: Automatically detects and integrates with various terminals across macOS, Linux, and Windows, including cmux and tmux for advanced multiplexing.
• Configurable Synchronization: Allows defining files to copy, directories to symlink, and patterns to exclude, ensuring each worktree has the necessary context.
• Custom Hooks: Supports postCreate and preDelete hooks for running custom commands, such as pnpm install or docker compose up -d.

This plugin transforms worktrees from a manual tool into an integral part of an automated development workflow, especially when paired with tools like cmux.

Installation

To install opencode-worktree, you'll need OCX installed. If you don't have OCX, follow the instructions on its repository first.

Once OCX is ready, add the plugin using the following command:

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

For a more comprehensive experience, consider installing kdco-workspace, which bundles worktrees with background agents, planning tools, and notifications:

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

Examples

The plugin introduces two primary tools for managing worktrees:

Creating a Worktree

Use worktree_create to set up a new isolated environment. A new terminal will spawn with OpenCode ready.

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

Upon execution, this command:

1. Creates a git worktree at ~/.local/share/opencode/worktree/<project-id>/feature/dark-mode.
2. Synchronizes files based on your .opencode/worktree.jsonc configuration.
3. Runs any defined postCreate hooks (e.g., pnpm install).
4. Opens a new terminal window with OpenCode running within the worktree.

Deleting a Worktree

Use worktree_delete to remove the current worktree. All changes are automatically committed before removal.

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

When called, this command:

1. Executes any preDelete hooks (e.g., docker compose down).
2. Commits all pending changes with a snapshot message.
3. Removes the git worktree with --force.
4. Cleans up the session state.

Links

• GitHub Repository: kdcokenny/opencode-worktree
• OpenCode: sst/opencode
• OCX (OpenCode eXtensions): kdcokenny/ocx
• cmux: cmux.dev
• Related Plugin - opencode-workspace: kdcokenny/opencode-workspace
• Related Plugin - opencode-background-agents: kdcokenny/opencode-background-agents
• Related Plugin - opencode-notify: kdcokenny/opencode-notify