Worktree Plugin
Relevant source files
The following files were used as context for generating this wiki page:
The Worktree Plugin is an OpenCode extension designed to provide zero-friction isolation for AI-driven development. It enables the creation of isolated Git worktrees where each worktree automatically spawns its own terminal instance with OpenCode running inside. This eliminates the manual overhead of setting up environments, navigating directories, and cleaning up temporary branches.
The plugin manages the entire lifecycle of a development session, from forking existing session context (including plans and delegations) to performing automatic commits and cleaning up the filesystem upon completion. It is a core component of the kdco/workspace bundle, aimed at CLI-first users and autonomous AI agents.
Sources: facades/opencode-worktree/README.md:3-15, workers/kdco-registry/files/plugin/worktree.ts:13-22
Architecture and Workflow
The plugin operates as a lifecycle manager for Git worktrees, integrating closely with the OpenCode session management system. When a worktree is created, it doesn't just create a directory; it synchronizes essential project files, runs environment setup hooks, and forks the AI's current state to ensure continuity.
The diagram above illustrates the high-level flow from worktree creation to automatic cleanup.
Sources: facades/opencode-worktree/README.md:46-56, workers/kdco-registry/files/plugin/worktree.ts:602-675
Key Components and Tools
The Worktree Plugin exposes two primary tools to the AI or user: worktree_create and worktree_delete. These tools handle the complex orchestration of Git commands, filesystem operations, and terminal spawning.
Tools Reference
| Tool | Parameters | Description |
|---|---|---|
worktree_create | branch (string), baseBranch? (string) | Creates a new worktree at ~/.local/share/opencode/worktree/<project-id>/<branch>, syncs files, and opens a terminal. |
worktree_delete | reason (string) | Marks the worktree for deletion. It commits snapshots and removes the directory when the session idles. |
Sources: facades/opencode-worktree/README.md:75-84, workers/kdco-registry/files/plugin/worktree.ts:606-695
Session Forking
To maintain context, the plugin implements forkWithContext. This function ensures that when a new worktree session starts, it inherits the implementation plan and delegation history from the parent session.
// Copy plan from parent to forked session
const srcPlan = path.join(workspaceBase, projectId, rootSessionId, "plan.md");
const destPlan = path.join(destWorkspaceDir, "plan.md");
planCopied = await copyIfExists(srcPlan, destPlan);
Sources: workers/kdco-registry/files/plugin/worktree.ts:167-176, workers/kdco-registry/files/plugin/worktree.ts:192-195
Terminal Spawning and Platform Support
A standout feature is the automatic detection and spawning of terminals. The plugin prioritizes tmux for seamless window management but supports a wide range of terminal emulators across macOS, Linux, and Windows.
| Platform | Supported Terminals |
|---|---|
| macOS | Ghostty, iTerm2, Kitty, WezTerm, Alacritty, Warp, Terminal.app |
| Linux | Kitty, WezTerm, Alacritty, Ghostty, Foot, GNOME Terminal, Konsole |
| Windows | Windows Terminal (wt.exe), cmd.exe fallback |
| Cross-Platform | tmux (creates new window instead of app window) |
Sources: facades/opencode-worktree/README.md:111-125
Configuration and Synchronization
The plugin utilizes a configuration file located at .opencode/worktree.jsonc. This file defines how the worktree environment is prepared.
Configuration Schema (worktree.jsonc)
| Section | Field | Description |
|---|---|---|
sync | copyFiles | Array of relative paths to copy (e.g., .env) |
sync | symlinkDirs | Directories to symlink to save space (e.g., node_modules) |
hooks | postCreate | Shell commands to run after creation (e.g., npm install) |
hooks | preDelete | Shell commands to run before removal (e.g., docker compose down) |
Sources: workers/kdco-registry/schemas/worktree.json:11-53, workers/kdco-registry/files/plugin/worktree.ts:497-535
Security and Validation
The plugin adheres to strict security principles, particularly regarding branch names and path safety to prevent shell injection and directory traversal.
- Branch Validation: Blocks control characters, Git ref characters (
~^:?*[]\\), and shell metacharacters (;&|$()`). - Path Safety: Validates that sync paths do not escape the project root and rejects absolute paths.
- Fail Loud: Implements "Elegant Defense" by throwing clear
WorktreeErrorexceptions for fallible operations.
Sources: workers/kdco-registry/files/plugin/worktree.ts:51-115, workers/kdco-registry/files/plugin/worktree.ts:430-450, examples/registry-starter/AGENTS.md:37-65
Summary
The Worktree Plugin serves as an essential automation layer for AI-driven development within the OCX ecosystem. By automating the lifecycle of isolated Git environments—including file synchronization, hook execution, and terminal management—it allows developers and AI agents to iterate rapidly in safe, throwaway environments without polluting the main working directory.
Sources: facades/opencode-worktree/README.md:143-160, workers/kdco-registry/files/plugin/worktree.ts:13-22