kugetsu/skills/opencode-worktree/SKILL.md

opencode-worktree

Isolated OpenCode sessions via git worktrees.

Overview

Each OpenCode session gets its own git worktree with a unique branch. This prevents:

• Clashes with parallel sessions on the same repo
• Accidental overwrites from multiple agents
• Confusion from work-in-progress across contexts

Prerequisites

• Git
• opencode installed and configured

Installation

Option 1: Source directly (Recommended)

. skills/opencode-worktree/opencode-worktree.sh

Option 2: Copy to PATH

cp skills/opencode-worktree/opencode-worktree.sh ~/.local/bin/opencode-worktree
chmod +x ~/.local/bin/opencode-worktree

Usage

Create new session

. opencode-worktree.sh                    # session-20260327-a1b2c3
. opencode-worktree.sh refactor-auth      # session-20260327-a1b2c3-refactor-auth

Cleanup

. opencode-worktree.sh --cleanup          # remove all session-* worktrees
. opencode-worktree.sh --cleanup <name>   # remove specific worktree

How It Works

1. Cleanup - On every launch, removes all stale session-* worktrees and their branches
2. Create - Creates new worktree based on main with unique name: session-{timestamp}-{random6}[-{purpose}]
3. Launch - Changes into worktree and launches opencode
4. Exit - When opencode exits, you return to your original directory (worktree remains for review)

Example Workflow

# Start session for refactoring auth
. opencode-worktree.sh refactor-auth

# ... do work in opencode ...

# Exit opencode (worktree with your changes still exists)
# Later, resume or cleanup
. opencode-worktree.sh --cleanup session-20260327-a1b2c3-refactor-auth

Script

See opencode-worktree.sh for the full source.