Skip to main content

OpenCode Worktree

tip

563 GitHub stars — Zero-friction git worktrees for OpenCode. Auto-spawns terminals, syncs files, and cleans up on exit.

Overview​

Git worktrees allow you to check out multiple branches of the same repository simultaneously. OpenCode Worktree automates this process for AI agents: when an agent needs to work on a different branch or experiment, the plugin creates a detached worktree, syncs relevant files, spawns a terminal in that context, and cleans up when done.

When to Use​

ScenarioBenefit
Parallel feature workOne agent works on main while another experiments
Safe experimentationChanges in a worktree don't affect the working directory
Branch-specific contextEach worktree has its own git state and dependencies
Review and testCheck out PR branches without stashing current work

How It Works​

  1. Worktree creation — When the agent needs isolation, the plugin calls git worktree add.
  2. Context setup — A new terminal session spawns in the worktree directory.
  3. Dependency sync — If configured, dependencies are installed in the worktree.
  4. Agent operations — The agent works within the isolated worktree.
  5. Cleanup — When finished, the worktree is removed and the terminal is closed.

Installation​

{
  "plugin": ["opencode-worktree"]
}

Configuration​

Basic Setup​

{
  "plugin": ["opencode-worktree"],
  "opencode-worktree": {
    "auto_sync": true,
    "auto_cleanup": true,
    "base_directory": ".worktrees"
  }
}

Advanced Configuration​

{
  "opencode-worktree": {
    "auto_sync": true,
    "auto_cleanup": true,
    "base_directory": ".worktrees",
    "install_dependencies": true,
    "dependency_command": "npm install",
    "spawn_terminal": true,
    "terminal_command": "tmux new-window -c {worktree_path}"
  }
}

Usage​

Create a Worktree for an Agent​

/worktree create feature/new-api

The plugin creates a git worktree from the feature/new-api branch and opens a terminal in it.

List Active Worktrees​

/worktree list

Shows all active worktrees with their branch names, paths, and status.

Clean Up​

/worktree cleanup

Removes all stale worktrees. The plugin also cleans up automatically on session end if auto_cleanup is enabled.

Best Practices​

Worktree Hygiene​

  • Set a reasonable base_directory to keep worktrees organized.
  • Use auto_cleanup to prevent orphaned worktrees from accumulating.
  • Monitor disk usage — each worktree is a full checkout.

Integration with Agents​

  • Configure specific agents to use worktrees for dangerous operations.
  • Use worktrees for agents that need to modify dependencies or configuration files.

Performance Considerations​

  • Worktrees share the git object store, so they are space-efficient.
  • Running npm install in each worktree can be slow — consider using a shared cache.

GitHub​

  • Repo: kdcokenny/opencode-worktree
  • npm: opencode-worktree
  • Topics: git-worktree, isolation, parallel-development
  • Category: Workspace / Environment