opencode-worktrunk

An opencode plugin that lets agents manage git worktrees through the worktrunk CLI (wt). When an agent creates or switches to a worktree, the opencode session's working directory is rebound to that worktree automatically.

What it does

Provides five tools to opencode agents:

• worktrunk_create — Create a new worktree on a new branch. Session moves there.
• worktrunk_switch — Switch to an existing branch's worktree. Session moves there.
• worktrunk_merge — Merge the current branch into the target (default branch by default). Removes the worktree, session moves to the target.
• worktrunk_list — List all worktrees. Marks the active one.
• worktrunk_remove — Remove a worktree. Refuses if it's the active one.

After a create, switch, or merge, every tool (read, edit, bash, glob, grep, lsp) operates from the worktree root. No permission prompts for in-worktree file edits.

Requirements

• opencode 1.17+ (v1 file install) or 2.x (v2 package install)
• worktrunk (wt) v0.65.0+, installed and on PATH
• Bun for running tests

Install

V1 (file-based):

git clone <repo> ~/Projects/opencode-worktrunk
cd ~/Projects/opencode-worktrunk
bun install
ln -sf "$(pwd)/src/worktrunk-wt.ts" ~/.config/opencode/plugins/worktrunk-wt.ts

V2 (package):

{
  "plugins": ["@pplante/opencode-worktrunk"]
}

V2 loads server from package exports. No symlinks needed. For a local checkout path, run bun install in it first — dist/ keeps @opencode/plugin external and won't load without node_modules.

Restart opencode.

Test

bun test

Architecture

Pure helpers are extracted into testable modules. The plugin entry is thin glue.

| File | Responsibility | |---|---| | src/paths.ts | isUnderPath, resolvePath — path comparison and symlink resolution | | src/parse.ts | Parsers for wt --format json output (switch, list, merge, remove) | | src/args.ts | CLI argument builders for each wt subcommand | | src/state.ts | Per-session state map (active worktree path + branch) | | src/worktrunk-wt.ts | V1 server plugin entry — registers 5 tools and hooks (permission.ask, shell.env, tool.execute.before, message bootstrap) | | src/server.ts | V2 server plugin entry (Plugin.define, id worktrunk) — same 5 tools plus wt aliases, permission.evaluate / tool.execute.before / session.context hooks, session.deleted cleanup |

The session cwd rebind uses session.move in v2 and the control-plane move endpoint in v1. V2 has no per-session shell env hook, so it sets no extra env — shell cwd follows the moved session. V2 permission auto-allow covers the renamed edit / external_directory actions.

Hook approvals

Worktrunk project hooks (.config/wt.toml) need first-run approval. If an agent's tool call hits an unapproved hook, the plugin surfaces the error and tells the user to run wt config approvals add. The plugin never passes --yes to silence the approval gate.