Open Orchestrator

Appearance

Git worktrees are a powerful feature that allows you to have multiple working directories attached to a single repository. This is the foundation of Open Orchestrator's parallel development capabilities.

What is a Git Worktree? ​

A git worktree is an additional working tree linked to your repository. Unlike branches (which are just pointers), worktrees give you a complete working directory for a specific branch.

my-project/                   # Main worktree (main branch)
my-project-feat-auth/         # Worktree for feat/auth
my-project-fix-login/         # Worktree for fix/login

Each worktree:

  • Has its own working directory
  • Can be on a different branch
  • Shares the same git history
  • Has independent staged/unstaged changes

Why Worktrees Instead of Multiple Clones? ​

FeatureMultiple ClonesGit Worktrees
Disk spaceFull copy eachShared objects
Git historySeparateShared
Branch conflictsPossiblePrevented
Setup timeFull cloneInstant

With worktrees, you get the isolation of separate directories without duplicating your entire repository.

How Open Orchestrator Uses Worktrees ​

Task-Driven Creation ​

When you run owt new "Add user authentication", Open Orchestrator:

  1. Generates a branch name from your task description (e.g., feat/user-authentication)
  2. Creates a git worktree in the configured base directory
  3. Creates and checks out the new branch
  4. Sets up the environment (installs dependencies, copies .env, etc.)
  5. Launches a tmux session with your configured AI tool
bash
# Create a worktree from a task description
owt new "Add user authentication"

# With a specific template
owt new "Fix login timeout" -t bugfix

# With a specific AI tool
owt new "Build REST API" --ai-tool opencode

Naming Convention ​

By default, worktrees are named: {project}-{branch}

For a project called my-app with branch feat/user-authentication:

  • Worktree path: ../my-app-feat-user-authentication/
  • tmux session: owt-feat-user-authentication

You can customize this in .worktreerc:

toml
[worktree]
base_directory = "../worktrees"
naming_pattern = "{project}-{branch}"

Branch Management ​

Open Orchestrator handles branch creation automatically through task descriptions. The branch naming algorithm converts your description into a properly formatted branch name with the appropriate prefix.

bash
# Task-driven creation (recommended)
owt new "Add user authentication"
# Creates branch: feat/user-authentication

owt new "Fix the broken login page"
# Creates branch: fix/broken-login-page

owt new "Refactor database queries"
# Creates branch: refactor/database-queries

Worktree Constraints ​

Git enforces some rules for worktrees:

One Branch Per Worktree ​

You cannot have the same branch checked out in multiple worktrees. This prevents conflicting changes.

bash
# If feat/auth is checked out in a worktree, this fails:
git checkout feat/auth  # Error!

Shared Git Objects ​

All worktrees share the same .git directory (or link to it). Changes committed in one worktree are immediately visible in others.

Pruning Stale Entries ​

If you delete a worktree directory manually, git may have stale references:

bash
# Clean up stale worktree references
git worktree prune

Open Orchestrator handles this automatically during cleanup.

Manual Worktree Commands ​

While Open Orchestrator manages worktrees for you, here are the underlying git commands:

bash
# List worktrees
git worktree list

# Create a worktree
git worktree add ../path feature/branch

# Remove a worktree
git worktree remove ../path

# Prune stale references
git worktree prune

Best Practices ​

1. Keep Worktrees Organized ​

Use a consistent base directory for all worktrees:

toml
[worktree]
base_directory = "../worktrees"

This keeps your project directory clean.

2. Clean Up Regularly ​

Use the cleanup command to remove stale worktrees:

bash
# Preview what would be cleaned
owt cleanup --dry-run

# Clean up worktrees older than 7 days
owt cleanup --days 7

3. Use the Control Plane for Navigation ​

Instead of manually tracking worktree sessions, use the Control Plane to see all active worktrees at a glance:

bash
# Launch the Control Plane
owt

4. Sync Before Long Sessions ​

Keep worktrees up to date with upstream:

bash
owt sync --all

Troubleshooting ​

"Branch is already checked out" ​

Another worktree has this branch. Either:

  • Delete the existing worktree: owt delete <name>
  • Use a different branch name

"Not a git repository" ​

Make sure you're in a git repository:

bash
git status

Stale Worktree Entries ​

If git worktree list shows entries that don't exist:

bash
git worktree prune

Next Steps ​