opencode-worktree

Git worktrees for isolated AI sessions, without terminal spawning.

An OpenCode plugin that creates isolated git worktrees, syncs selected files, runs lifecycle hooks, and tracks cleanup state.

Why This Exists

Manual worktrees are powerful but repetitive for AI workflows: create the worktree, set up context, and remember cleanup. This plugin turns that into a predictable tool-based flow.

• worktree_create creates a branch worktree and forks session context.
• worktree_delete marks the current worktree for cleanup and removes it on idle.
• Hook support (postCreate, preDelete) lets each repo define setup/teardown steps.

Installation

From npm (recommended)

Add to your opencode.json:

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

Local plugin file (no npm publish required)

Create a loader file in one of OpenCode's local plugin directories:

• Project-local: .opencode/plugins/worktree.ts
• Global: ~/.config/opencode/plugins/worktree.ts

Example global setup:

export { WorktreePlugin } from "./worktree/worktree.js"

Then copy dist/worktree.js to ~/.config/opencode/plugins/worktree/worktree.js.

Install runtime dependencies into ~/.config/opencode:

cd ~/.config/opencode
bun add @opencode-ai/plugin @opencode-ai/sdk jsonc-parser zod

Usage

The plugin adds two tools:

Tool	Purpose
worktree_create(branch, baseBranch?)	Create a new git worktree and fork session context for isolated work.
worktree_delete(reason)	Mark current worktree for cleanup; commits and removal happen when session idles.

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
3. Runs postCreate hooks
4. Forks session context and records the new worktree session mapping

Deleting a Worktree

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

When called, this:

1. Marks current worktree for deletion
2. Runs preDelete hooks on session.idle
3. Commits snapshot changes
4. Removes git worktree with --force
5. Clears tracked session state

Configuration

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

{
  "$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": []
  }
}

FAQ

What problem does this solve?

It standardizes AI worktree lifecycle management with file sync, hooks, and cleanup tracking.

Does this break normal git workflow?

No. It uses standard git worktree operations. Branches and merges work normally.

Can I still start terminals manually?

Yes. This plugin does not open terminals. You can open any shell/editor workflow you want in the created worktree path.

Development

bun install
bun unittest
bun typecheck
bun lint
bun format:check

Acknowledgments

Inspired by opencode-worktree-session by Felix Anhalt.

Disclaimer

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

License

MIT