OpenCode with Git Worktree

OpenCode is an open-source terminal-based AI coding assistant that works with multiple LLM providers. When combined with git worktree, you can run multiple OpenCode sessions in parallel, each in its own isolated branch and directory. This guide covers setup, workflow, and best practices.

What Is OpenCode?

OpenCode is a terminal-native AI coding tool that connects to various LLM backends (OpenAI, Anthropic, local models, and others) to help you write, debug, and refactor code. It runs in your terminal, reads your project files, and makes changes based on your instructions.

Like other AI coding tools, OpenCode modifies files directly in the working directory. This makes it a natural candidate for git worktrees: each OpenCode session gets its own directory and branch, preventing file conflicts when running multiple sessions.

How OpenCode Uses Worktrees

OpenCode does not have a built-in worktree flag like some other tools, but it works seamlessly with manually created git worktrees. The workflow is straightforward: create a worktree, navigate to it, and start OpenCode inside it.

Because OpenCode reads project context from the current directory, starting it inside a worktree means it sees only that worktree's files and branch. Any changes the AI agent makes are confined to that worktree, leaving your main checkout and other worktrees untouched.

Start OpenCode in a worktree

# Create a worktree for an OpenCode session
git worktree add ../project-feat-search -b feat/search

# Navigate to the worktree and start OpenCode
cd ../project-feat-search
opencode

Setup Guide

Follow these steps to set up a multi-session OpenCode workflow with git worktrees:

Step 1: Install OpenCode

Install OpenCode

# Install OpenCode via npm
npm install -g opencode

# Or via Homebrew
brew install opencode

# Verify installation
opencode --version

Step 2: Configure Your LLM Provider

OpenCode needs an LLM backend configured. Set up your provider in the OpenCode configuration file or via environment variables:

Configure LLM provider

# Set your API key (applies to all worktrees)
export OPENAI_API_KEY="sk-..."

# Or for Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

Step 3: Create Worktrees

Create a worktree for each task you want to run in parallel:

Create worktrees for OpenCode

# Create worktrees for different tasks
git worktree add ../project-feat-api -b feat/api-endpoints
git worktree add ../project-fix-tests -b fix/broken-tests
git worktree add ../project-refactor -b refactor/database-layer

# List all worktrees
git worktree list

Step 4: Launch OpenCode in Each Worktree

Open separate terminal tabs or tmux panes and start OpenCode in each worktree:

Launch parallel OpenCode sessions

# Terminal 1
cd ../project-feat-api && opencode

# Terminal 2
cd ../project-fix-tests && opencode

# Terminal 3
cd ../project-refactor && opencode

Multi-Session Workflow

Using tmux makes managing multiple OpenCode sessions much easier. You can see all sessions at a glance and switch between them quickly:

opencode-parallel.sh

#!/bin/bash
# opencode-parallel.sh - Launch parallel OpenCode sessions in tmux

SESSION="opencode-work"
REPO_DIR=$(pwd)

# Create worktrees
git worktree add ../oc-feat -b feat/new-feature
git worktree add ../oc-fix -b fix/bug-report-42
git worktree add ../oc-docs -b docs/api-reference

# Start tmux session
tmux new-session -d -s $SESSION -c ../oc-feat
tmux send-keys -t $SESSION "opencode" Enter

# Add panes for other worktrees
tmux split-window -h -t $SESSION -c ../oc-fix
tmux send-keys -t $SESSION "opencode" Enter

tmux split-window -v -t $SESSION -c ../oc-docs
tmux send-keys -t $SESSION "opencode" Enter

# Attach to session
tmux attach-session -t $SESSION

Each OpenCode session runs independently. You can give each session different instructions, and they will work on their respective tasks without interfering with each other. When all sessions are done, review each branch and merge the ones you want to keep.

Review and merge results

# After sessions complete, review changes
git diff main..feat/new-feature
git diff main..fix/bug-report-42
git diff main..docs/api-reference

# Merge the branches you want
git checkout main
git merge feat/new-feature
git merge fix/bug-report-42
git merge docs/api-reference

# Clean up worktrees
git worktree remove ../oc-feat
git worktree remove ../oc-fix
git worktree remove ../oc-docs
git worktree prune

Tips

Share Configuration Across Worktrees

OpenCode reads its configuration from the project root. Since worktrees share the same git history, configuration files tracked by git (like .opencode.json) are automatically available in every worktree.

Environment Variables Apply Globally

API keys set as environment variables in your shell are available to all OpenCode sessions, regardless of which worktree they run in. You do not need to set them per worktree.

Assign Non-Overlapping Tasks

While worktrees prevent file-level conflicts during development, you will still need to merge branches afterward. Assigning tasks that touch different parts of the codebase minimizes merge conflicts. For example, one agent on the API layer, another on the UI, and a third on tests.

Use OpenCode with Other AI Tools

Since OpenCode works with standard git worktrees, you can use it alongside other AI tools. For example, run OpenCode in one worktree and Claude Code in another, each on its own branch.

Summary

OpenCode and git worktrees work well together for parallel AI development. Create a worktree for each task, launch OpenCode in each one, and let the agents work independently. Use tmux to manage multiple sessions, and merge the results when done. For more on parallel patterns, see the parallel agents guide, or learn the fundamentals of git worktree.