diff --git a/README.md b/README.md index 4256649..2b0ea40 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,21 @@ # opencode-worktree -Git worktree manager for isolated [OpenCode](https://opencode.ai) agent sessions. Create an isolated worktree, launch OpenCode in it, and auto-merge back when done. +Git worktree manager for isolated [OpenCode](https://opencode.ai) agent sessions. + +Run multiple AI agents in parallel — each gets its own branch and directory, fully isolated from your working tree. When they're done, changes merge back automatically. No stashing, no branch juggling, no conflicts between agents. ## Why? -When using AI coding agents on complex tasks, you want isolation — the agent works on a branch in a separate directory, and you merge its changes back only when ready. This tool automates the entire lifecycle: +AI coding agents work best with full autonomy over their environment. But you don't want them trampling your working directory — or each other. `opencode-worktree` gives each agent an isolated workspace and handles the entire lifecycle: 1. **Create** an `agent/` branch in a sibling worktree directory -2. **Launch** OpenCode TUI in that worktree +2. **Launch** OpenCode in that worktree with your config copied over 3. **Merge** the agent branch back into your parent branch on exit 4. **Clean up** the worktree and branch automatically -## Install - -### LLM Agent Install - -Paste this into your LLM agent session: +No manual git commands. No orphaned branches. Multiple agents can run simultaneously with safe, serialized merges. -``` -Install opencode-worktree by following the instructions here: -https://raw.githubusercontent.com/DanHenton/opencode-worktree/main/docs/install.md -``` +## Install ### Quick Install (macOS / Linux) @@ -28,75 +23,16 @@ https://raw.githubusercontent.com/DanHenton/opencode-worktree/main/docs/install. curl -fsSL https://raw.githubusercontent.com/DanHenton/opencode-worktree/main/install.sh | sh ``` -Override the install directory with `BIN_DIR`: - -```bash -curl -fsSL https://raw.githubusercontent.com/DanHenton/opencode-worktree/main/install.sh | BIN_DIR=/usr/local/bin sh -``` - -### Install with Go - -Requires Go 1.24+. - -```bash -go install github.com/danhenton/opencode-worktree/cmd/opencode-worktree@latest -``` - -If `opencode-worktree` isn't found after install, add Go's bin directory to your PATH: - -```bash -# Find where Go put it -go env GOPATH # binary is in the bin/ subdirectory of this path - -# Add to your shell profile (zsh) -echo 'export PATH="$(go env GOPATH)/bin:$PATH"' >> ~/.zshrc - -# Add to your shell profile (bash) -echo 'export PATH="$(go env GOPATH)/bin:$PATH"' >> ~/.bashrc - -# Then open a new terminal, or: -export PATH="$(go env GOPATH)/bin:$PATH" -``` - -### Manual Download - -Download a release directly from GitHub: - -```bash -# macOS (Apple Silicon) -curl -fsSLO https://github.com/DanHenton/opencode-worktree/releases/latest/download/opencode-worktree_Darwin_arm64.tar.gz - -# macOS (Intel) -curl -fsSLO https://github.com/DanHenton/opencode-worktree/releases/latest/download/opencode-worktree_Darwin_x86_64.tar.gz - -# Linux (x86_64) -curl -fsSLO https://github.com/DanHenton/opencode-worktree/releases/latest/download/opencode-worktree_Linux_x86_64.tar.gz - -# Linux (ARM64) -curl -fsSLO https://github.com/DanHenton/opencode-worktree/releases/latest/download/opencode-worktree_Linux_arm64.tar.gz -``` +### LLM Agent Install -Then extract and install: +Paste this into your LLM agent session: -```bash -tar -xzf opencode-worktree_*.tar.gz -mkdir -p ~/.local/bin -install -m 0755 opencode-worktree ~/.local/bin/opencode-worktree ``` - -If `~/.local/bin` isn't in your PATH, add it to your shell profile: - -```bash -# zsh -echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc - -# bash -echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc +Install opencode-worktree by following the instructions here: +https://raw.githubusercontent.com/DanHenton/opencode-worktree/main/docs/install.md ``` -Then open a new terminal. - -See all available builds on the [Releases Page](https://github.com/DanHenton/opencode-worktree/releases). +For other install methods (Go, manual download, PATH troubleshooting), see the [full install guide](docs/install.md). ## Usage @@ -111,6 +47,7 @@ This will: - Create worktree at `../your-repo-agent-fix-auth-bug/` - Create branch `agent/fix-auth-bug` from your current branch - Copy `opencode.json` and `.opencode/` into the worktree +- Detect dependency manifests (`package.json`, `go.mod`, etc.) and tell the agent to install them - Launch `opencode` in the worktree - Auto-merge back into your branch when you exit OpenCode @@ -186,7 +123,9 @@ Each worktree gets two marker files: ## AGENTS.md Integration -Add this section to your project's `AGENTS.md` to give AI agents context about their worktree environment: +When `opencode-worktree` launches an agent session, it automatically injects worktree context into the initial message — including branch info, detected dependency manifests, and install commands. No configuration needed. + +Optionally, add this section to your project's `AGENTS.md` for additional guidance: ```markdown ## Worktree Agent Sessions diff --git a/docs/install.md b/docs/install.md index e81db4e..066bdb4 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,21 +1,90 @@ -# Installation +# Install Guide -## For Humans +All methods for installing `opencode-worktree`. For a quick overview, see the [README](../README.md). -Paste this into your LLM agent session: +## Quick Install (macOS / Linux) +```bash +curl -fsSL https://raw.githubusercontent.com/DanHenton/opencode-worktree/main/install.sh | sh ``` -Install opencode-worktree by following the instructions here: -https://raw.githubusercontent.com/DanHenton/opencode-worktree/main/docs/install.md + +Auto-detects OS and architecture, downloads the correct release from GitHub, and places it in `~/.local/bin/`. + +Override the install directory: + +```bash +curl -fsSL https://raw.githubusercontent.com/DanHenton/opencode-worktree/main/install.sh | BIN_DIR=/usr/local/bin sh ``` -**Or install it yourself:** +## Install with Go + +Requires Go 1.24+. ```bash -curl -fsSL https://raw.githubusercontent.com/DanHenton/opencode-worktree/main/install.sh | sh +go install github.com/danhenton/opencode-worktree/cmd/opencode-worktree@latest +``` + +## Manual Download + +Download a release directly from the [Releases Page](https://github.com/DanHenton/opencode-worktree/releases): + +```bash +# macOS (Apple Silicon) +curl -fsSLO https://github.com/DanHenton/opencode-worktree/releases/latest/download/opencode-worktree_Darwin_arm64.tar.gz + +# macOS (Intel) +curl -fsSLO https://github.com/DanHenton/opencode-worktree/releases/latest/download/opencode-worktree_Darwin_x86_64.tar.gz + +# Linux (x86_64) +curl -fsSLO https://github.com/DanHenton/opencode-worktree/releases/latest/download/opencode-worktree_Linux_x86_64.tar.gz + +# Linux (ARM64) +curl -fsSLO https://github.com/DanHenton/opencode-worktree/releases/latest/download/opencode-worktree_Linux_arm64.tar.gz +``` + +Extract and install: + +```bash +tar -xzf opencode-worktree_*.tar.gz +mkdir -p ~/.local/bin +install -m 0755 opencode-worktree ~/.local/bin/opencode-worktree +``` + +## PATH Troubleshooting + +If `opencode-worktree` isn't found after install, the install directory isn't in your PATH. + +**If installed via install.sh or manual download** (default: `~/.local/bin`): + +```bash +# zsh +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc + +# bash +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc +``` + +**If installed via `go install`:** + +```bash +# zsh +echo 'export PATH="$(go env GOPATH)/bin:$PATH"' >> ~/.zshrc + +# bash +echo 'export PATH="$(go env GOPATH)/bin:$PATH"' >> ~/.bashrc ``` -## For LLM Agents +Then open a new terminal, or run `export PATH=...` directly to apply immediately. + +## Requirements + +- **OS**: macOS or Linux (Windows: download manually from [Releases](https://github.com/DanHenton/opencode-worktree/releases)) +- **Dependencies**: `git`, `opencode` (the [OpenCode TUI](https://opencode.ai) must be installed separately) +- **Optional**: Go 1.24+ (only for `go install` method) + +--- + +## LLM Agent Install > **IMPORTANT: Use `curl` to fetch this file, NOT WebFetch.** WebFetch may summarize content and lose critical details. Always use: > @@ -39,7 +108,7 @@ If already installed, skip to Step 4. ### Step 2: Install the binary -Run the installer script. This auto-detects OS (macOS/Linux) and architecture (x86_64/arm64/armv7/i386), downloads the correct release from GitHub, and places it in `~/.local/bin/`. +Run the installer script: ```bash curl -fsSL https://raw.githubusercontent.com/DanHenton/opencode-worktree/main/install.sh | sh @@ -110,9 +179,3 @@ opencode-worktree task my-task-name # Start with an initial prompt opencode-worktree task my-task-name "Description of what to work on" ``` - -### Requirements - -- **OS**: macOS or Linux (Windows: download manually from [Releases](https://github.com/DanHenton/opencode-worktree/releases)) -- **Dependencies**: `git`, `opencode` (the OpenCode TUI must be installed separately) -- **Optional**: Go 1.24+ (only for `go install` method) diff --git a/internal/worktree/worktree.go b/internal/worktree/worktree.go index 1ef8388..47c7308 100644 --- a/internal/worktree/worktree.go +++ b/internal/worktree/worktree.go @@ -99,7 +99,7 @@ func copyOpenCodeConfig(repoRoot, worktreeDir string) error { func LaunchOpenCode(worktreeDir, initialPrompt string) error { var cmd *exec.Cmd if initialPrompt != "" { - cmd = exec.Command("opencode", "--message", initialPrompt) + cmd = exec.Command("opencode", "--prompt", initialPrompt) } else { cmd = exec.Command("opencode") }