Open Orchestrator

Appearance

General Questions ​

What is Open Orchestrator? ​

Open Orchestrator is a lean CLI tool (7 dependencies) for git worktree + AI coding tool orchestration. It enables developers to work on multiple tasks simultaneously by creating isolated worktrees, each with its own tmux session and AI coding tool instance. It provides 20+ commands and a Textual-based Control Plane for managing everything.

What AI tools does it support? ​

  • Claude Code (default) - Anthropic's CLI for Claude
  • OpenCode - Go-based AI coding assistant
  • Droid - Factory's AI with configurable autonomy

The AI tool picker (Alt+c) also detects Codex, Gemini CLI, Aider, Amp, and Kilo Code if installed.

Do I need tmux? ​

Yes, tmux is required. Open Orchestrator uses tmux for session management and the Control Plane interface.

Does it work on Windows? ​

Currently, Open Orchestrator is designed for Unix-like systems (macOS, Linux). Windows support via WSL may work but is not officially supported.

Installation ​

What Python version do I need? ​

Python 3.10 or higher is required.

Can I install globally? ​

Yes:

bash
pip install open-orchestrator

Or with uv:

bash
uv pip install open-orchestrator

How do I update? ​

bash
# If installed from source
cd /path/to/open-orchestrator
git pull
pip install -e .

# If installed from PyPI
pip install --upgrade open-orchestrator

What are the dependencies? ​

Open Orchestrator has only 7 dependencies: click, pydantic, rich, toml, gitpython, libtmux, and textual.

Worktrees ​

What is a git worktree? ​

A git worktree is an additional working directory linked to your repository. Unlike branches, worktrees give you a complete working directory for a specific branch. See Git Worktrees.

Where are worktrees created? ​

By default, worktrees are created as siblings to your main repository:

my-project/                          # Main repo
my-project-feat-user-authentication/ # Worktree
my-project-feat-build-rest-api/      # Worktree

Configure in .worktreerc:

toml
[worktree]
base_directory = "../worktrees"  # Custom location

Can I have the same branch in multiple worktrees? ​

No, git doesn't allow the same branch to be checked out in multiple worktrees. This prevents conflicting changes.

How do I delete all worktrees? ​

bash
owt cleanup --no-dry-run --yes

Or manually:

bash
git worktree list
git worktree remove <path>

How does branch naming work? ​

When you run owt new "task description", the description is automatically converted to a branch name. For example, owt new "Add user authentication" creates branch feat/user-authentication. See Branch Naming.

Control Plane ​

What is the Control Plane? ​

The Control Plane is a Textual-based, prioritized decision surface launched by running owt with no arguments. It groups active worktrees into three lanes (NEEDS YOU, READY TO SHIP, IN FLIGHT) so you can see what needs attention at a glance and navigate between them.

How do I navigate the Control Plane? ​

  • Arrow keys to move between worktrees
  • Enter to patch in to a worktree session
  • Alt+s to return to the Control Plane
  • Alt+m to merge current worktree
  • Alt+d to delete current worktree
  • Alt+c to create a new worktree
  • q to quit

tmux ​

How do I detach from a tmux session? ​

Press Ctrl+B, D. Or use Alt+s to return to the Control Plane (recommended).

Can I customize tmux keybindings? ​

Yes, your ~/.tmux.conf settings apply to Open Orchestrator sessions.

Commands ​

What commands does Open Orchestrator have? ​

Open Orchestrator has 20+ commands. Core commands include: owt (control plane), new (with --workflow for plan-first runs), list, switch, send, merge, ship, delete, queue, wait, note, sync, cleanup, version, usage, config validate, config show, db purge, db vacuum, db health, doctor, branch, and attach.

How do I see what the AI is working on? ​

Open the Control Plane:

bash
owt

Each worktree shows the current status and task.

Can I send multi-line commands? ​

Yes:

bash
owt send feat/auth "Please implement:
1. Login endpoint
2. Logout endpoint
3. Session management"

How does merge work? ​

owt merge uses a two-phase approach: first it merges base into feature (to catch conflicts safely), then fast-forwards feature into base.

Configuration ​

Where is the config file? ​

Open Orchestrator looks in this order:

  1. .worktreerc in project
  2. .worktreerc.toml in project
  3. ~/.config/open-orchestrator/config.toml
  4. ~/.worktreerc

How do I set defaults for all projects? ​

Create ~/.config/open-orchestrator/config.toml:

toml
[tmux]
ai_tool = "claude"
auto_start_ai = true

How do I override project detection? ​

In .worktreerc:

toml
[project]
type = "python"
package_manager = "uv"
install_command = "uv sync"

Templates ​

What templates are available? ​

Three built-in templates: feature (plan mode, TDD), bugfix (root cause analysis), and hotfix (minimal fix). You can define custom templates in .worktreerc.

How do I use a template? ​

bash
owt new "Fix login bug" -t bugfix

Status & Monitoring ​

Where is status data stored? ​

~/.open-orchestrator/status.db

What status values exist? ​

IDLE, WORKING, BLOCKED, WAITING, COMPLETED, ERROR, and UNKNOWN.

Claude Code Integration ​

How do I install the skill? ​

bash
owt skill install

What slash commands are available? ​

  • /worktree - Main management command
  • /wt-create - Quick create
  • /wt-list - List worktrees
  • /wt-cleanup - Clean up

Do I need to configure permissions? ​

Yes, add to .claude/settings.json:

json
{
  "permissions": {
    "allow": ["Bash(owt:*)"]
  }
}

Troubleshooting ​

Why isn't my AI tool starting? ​

  1. Check it's installed: which claude
  2. Open the Control Plane and patch in to see errors: owt then Enter
  3. Check your .worktreerc configuration

Why are dependencies not installing? ​

  1. Check project detection with --verbose flag
  2. Override if needed in .worktreerc
  3. Install manually in the worktree directory

How do I reset everything? ​

bash
# Delete all worktrees
owt cleanup --no-dry-run --force --yes

# Clear status data
rm ~/.open-orchestrator/status.db

Best Practices ​

How many worktrees should I have? ​

There's no hard limit, but consider:

  • Memory usage (each tmux session uses resources)
  • Disk space (worktrees share git objects)
  • Cognitive load (more to track)

A practical limit is 5-10 active worktrees.

Should I commit work in worktrees? ​

Yes, commit and push regularly. Worktrees are temporary workspaces, not backups.

When should I clean up? ​

  • After features are merged
  • Weekly for stale worktrees
  • When running low on disk space
bash
owt cleanup --days 7 --no-dry-run

See Also ​