This plugin ensures your main working directory remains clean while the AI works in an isolated branch. On session end, it automatically generates a commit message, pushes the branch, and removes the worktree.

Features

Isolation: Automatically creates a new Git worktree in .opencode/worktrees/.
Safety: Refuses to run on the main branch to prevent accidental corruption.
Context-Aware: Pivots the AI's working directory (cwd) to the worktree automatically.
Automated Cleanup: Commits changes using AI-generated messages and deletes the worktree upon exit.

Installation

NPM

Add to your opencode.json:

{
  "plugin": ["@tmegit/opencode-worktree-session"]
}

Workflow

Start Session: Run opencode.
Branch Prompt: You will be prompted for a branch suffix (e.g., feature-xyz).
Worktree Creation: The plugin creates opencode/feature-xyz and moves the session into that path.
Execution: The AI performs tasks inside the isolated worktree.
Exit: Upon closing the session, the plugin:

Stages all changes.
Generates a commit message via OpenCode API.
Pushes to origin.
Removes the worktree safely.

Requirements

Node.js runtime
Git installed and configured in PATH
OpenCode CLI

Config

Example (save as .opencode/opencode-worktree-session-config.json):

{
  "terminal": {
    "mode": "custom",
    "bin": "alacritty",
    "args": "",
    "workingDirectoryArgument": "--working-directory",
    "commandFlag": "-e"
  },
  "postWorktree": {
    "cmd": "webstorm",
    "args": ""
  },
  "configToolsAvailable": false
}

Configure the plugin in .opencode/opencode-worktree-session-config.json.

terminal — Controls how the plugin launches a terminal.
- mode — launch mode: default | custom | specific
- bin — terminal binary
- args — extra args
- workingDirectoryArgument — workdir flag
- commandFlag — command flag
- terminal (specific mode) — Alacritty, iTerm, iTerm2, Terminal
postWorktree — Command run after worktree creation.
- cmd — command to run
- args — command args
configToolsAvailable — Enable or disable config helper tools (affects setpostworktree, setworktreesync, setterminal).
- boolean — true/false