Open Trees Setup

0) Prereqs (check these first)

• Bun installed: bun --version
• OpenCode installed: opencode --version
• Git 2.15+ installed: git --version

1) Install + register the plugin (one command)

bunx open-trees add

What this does:

1. Creates/updates ~/.config/opencode/opencode.json
2. Adds "open-trees" to the plugin array

If your config file lives elsewhere:

bunx open-trees add --config /path/to/opencode.json

2) Start OpenCode (this actually installs the plugin)

opencode

Restarting opencode will ensure the plugin is properly set up.

3) Turn on worktree mode (required before any worktree tools work)

/worktree on 

4) Create your first worktree

Create only:

worktree_make { "action": "create", "name": "feature audit" }

Create + open a session in it:

worktree_make { "action": "start", "name": "feature audit", "openSessions": true }

worktree_mode

This gates all other worktree tools so they do not clutter your tool list, how it works:

/worktree on
/worktree off

Open Trees

OpenCode plugin for fast, safe git worktree workflows.

Install

Single command (recommended):

bunx open-trees add

This updates your OpenCode config (default: ~/.config/opencode/opencode.json). OpenCode installs npm plugins automatically at startup (cached in ~/.cache/opencode/node_modules).

Manual config:

{
  "plugin": ["open-trees"]
}

For local development, build the plugin and point OpenCode at the local package:

bun install
bun run build

{
  "plugin": ["/absolute/path/to/open-trees"]
}

Worktree mode

Worktree tools are gated behind worktree mode so they do not clutter the default tool list. Enable it when you want to work with worktrees, then disable it when you are done.

worktree_mode { "action": "on" }
worktree_mode { "action": "off" }

worktree_mode also prints a help sheet (tools + examples) so the model has the usage context.

Slash-native toggle (see .opencode/command/worktree.md):

/worktree on
/worktree off

/worktree on enables the tools and emits the help sheet into the session. /worktree off disables them and keeps them off for the next session.

Tools

• worktree_mode — enable/disable worktree mode and show help.
• worktree_overview — list, status, or dashboard worktrees.
• worktree_make — create/open/fork worktrees and sessions.
• worktree_cleanup — remove or prune worktrees safely.

Examples

Enable worktree mode:

worktree_mode { "action": "on" }

List worktrees:

worktree_overview

Status for all worktrees:

worktree_overview { "view": "status" }

Show the worktree/session dashboard:

worktree_overview { "view": "dashboard" }

Create a worktree (branch derived from name):

worktree_make { "action": "create", "name": "feature audit" }

Start a new session (creates or reuses a worktree):

worktree_make { "action": "start", "name": "feature audit", "openSessions": true }

Open a session in an existing worktree:

worktree_make { "action": "open", "pathOrBranch": "feature/audit", "openSessions": true }

Fork the current session into a worktree:

worktree_make { "action": "fork", "name": "feature audit", "openSessions": true }

Create a swarm of worktrees/sessions:

worktree_make { "action": "swarm", "tasks": ["refactor-auth", "docs-refresh"], "openSessions": true }

Remove a worktree:

worktree_cleanup { "action": "remove", "pathOrBranch": "feature/audit" }

Prune stale worktree entries:

worktree_cleanup { "action": "prune", "dryRun": true }

Defaults and safety

• Default worktree path (when path is omitted):
  • <repo>/.worktrees/<branch>
• Relative path inputs are resolved under .worktrees/ to prevent traversal.
• Branch name is derived from name when branch is omitted (lowercased, spaces to -).
• worktree_cleanup refuses to delete dirty worktrees unless force: true.
• All tools return readable output with explicit paths and git commands.

Session workflow

worktree_make actions (start, open, fork) create or reuse a worktree, then create a session in that directory. Each action records a mapping entry at:

• ~/.config/opencode/open-trees/state.json (or ${XDG_CONFIG_HOME}/opencode/open-trees/state.json)

The session title defaults to wt:<branch>, and the output includes the session ID plus next steps.

Swarm safety notes:

• worktree_make with action: "swarm" refuses to reuse existing branches or paths unless force: true.
• It never deletes existing worktrees; it only creates new ones.

Optional command file examples:

# .opencode/command/worktree.md
worktree_mode { "action": "$1" }

# .opencode/command/worktree-start.md
worktree_make { "action": "start", "name": "$1", "openSessions": true }

# .opencode/command/worktree-open.md
worktree_make { "action": "open", "pathOrBranch": "$1", "openSessions": true }

Slash commands (drop these files into .opencode/command):

/worktree on
/worktree off
/worktree-overview
/worktree-make <name>
/worktree-clean <pathOrBranch>

Development

E2E tests exercise the CLI against a temporary OpenCode config file.

bun run lint
bun run typecheck
bun run build
bun run test
bun run test:e2e
bun pm scan
npm audit --omit=dev

Versioning

Open Trees follows Semantic Versioning and tracks notable changes in CHANGELOG.md.

Brand

Brand visuals, SVG assets, and usage guidelines live in docs/brand.md.

Contributing

See CONTRIBUTING.md for setup, testing, and release guidelines.