Open Orchestrator

Appearance

This guide walks through the full lifecycle of a worktree — from task description to merge — explaining what happens at each step.

Prerequisites ​

Before starting, make sure you have:

  • Open Orchestrator installed (owt version works)
  • A git repository to work with
  • tmux installed
  • An AI coding tool installed (Claude Code, Pi, OpenCode, or Droid)

Step 1: Describe Your Task ​

Navigate to your project and describe what you want done:

bash
cd ~/projects/my-app

owt new "Implement login form with email and password"

What happens: Branch name generation ​

Open Orchestrator parses your task description and generates a branch name. You see a confirmation prompt:

Task: Implement login form with email and password
Branch: implement-login-form
Accept? [Y/n/edit]:

Press Enter to accept, or type edit to customize the branch name. The branch name is derived from your task — no need to come up with naming conventions.

Step 2: Watch the Setup ​

After you confirm, Open Orchestrator runs through the full setup sequence:

Creating worktree...
  Branch: implement-login-form
  Path:   ../my-app-implement-login-form

Detecting project type...
  Detected: node (npm)

Installing dependencies...
  Running: npm install
  Done.

Setting up environment...
  Copied .env
  Copied CLAUDE.md (paths adjusted)

Creating tmux session...
  Session: owt-implement-login-form

Launching AI agent...
  Tool: claude-code
  Task: "Implement login form with email and password"

Ready. Worktree is active.

Here is what each step does:

  1. Branch naming — The branch name is derived from your task description. You confirm or edit before anything is created.
  2. Worktree creation — A new git worktree is created in a sibling directory (e.g., ../my-app-implement-login-form/). This is a full copy of your repo on a new branch — completely isolated from your main working directory.
  3. Project detection — Open Orchestrator inspects the repo for package.json, requirements.txt, Cargo.toml, go.mod, or composer.json to determine the project type.
  4. Dependency installation — The appropriate package manager runs (npm install, pip install -r requirements.txt, cargo build, etc.) so the worktree is immediately ready.
  5. Environment setup — .env files and CLAUDE.md are copied into the new worktree with paths adjusted.
  6. tmux session — A dedicated tmux session is created for this worktree, named owt-<branch-name>.
  7. AI agent launch — Your configured AI tool (Claude Code, Pi, OpenCode, or Droid) is launched inside the tmux session with your task description as the initial prompt.

Step 3: Navigate via the Control Plane ​

While the AI agent works in the background, launch the Control Plane:

bash
owt

You see a Textual decision surface showing all your worktrees grouped by what needs attention. The new worktree appears with a working status light, meaning the AI agent is actively coding.

+---------------------------+---------------------------+
| main                      | implement-login-form      |
| Branch: main              | Branch: implement-login.. |
| Status: -                 | Status: working           |
+---------------------------+---------------------------+

Use arrow keys to navigate and Enter to jump into a worktree's tmux session.

Step 4: Send Additional Instructions ​

You can send follow-up instructions to the AI agent without entering the tmux session:

bash
owt send implement-login-form "Add form validation — email must be valid, password minimum 8 characters"

The message is sent to the AI agent's tmux pane. You stay in your current terminal.

You can also chain multiple tasks:

bash
owt send implement-login-form "After the form is done, add unit tests for the validation logic"

Step 5: Review the Work ​

When you want to see what the AI has produced, jump into the session:

bash
owt switch implement-login-form

Or press Enter on the worktree in the Control Plane.

You are now inside the tmux session with the AI agent. You can:

  • Review the code changes the AI has made
  • Ask the AI follow-up questions directly
  • Make manual edits alongside the AI

Returning to the Control Plane ​

Press Alt+s to return to the Control Plane. This is a global tmux keybinding that works from inside any worktree session.

Press Alt+c to create a new worktree without leaving tmux.

Step 6: Merge When Done ​

Once you are satisfied with the work, run the two-phase merge:

bash
owt merge implement-login-form

What happens: Two-phase merge ​

  1. Phase 1 — Merge: The branch is merged into your base branch (typically main).
  2. Phase 2 — Verify: The merge result is checked for conflicts or issues.
  3. Cleanup: On success, the worktree directory, git branch, and tmux session are all removed automatically.
Merging implement-login-form into main...
  Phase 1: Merge complete
  Phase 2: Verification passed

Cleaning up...
  Removed worktree: ../my-app-implement-login-form
  Deleted branch: implement-login-form
  Closed tmux session: owt-implement-login-form

Done.

Working With Multiple Worktrees ​

The real power of Open Orchestrator shows when you run multiple worktrees in parallel:

bash
# Kick off three tasks at once
owt new "Implement login form with email and password"
owt new "Add rate limiting to the API endpoints"
owt new "Write integration tests for user registration"

# Monitor all three from the Control Plane
owt

# Send follow-ups to any of them
owt send rate-limiting "Also add per-IP rate limits"

# Merge them as they complete
owt merge login-form
owt merge rate-limiting
owt merge integration-tests

Each worktree is fully isolated — different branch, different directory, different AI agent session. No conflicts until merge time.

Using Templates ​

For common task types, use templates to get sensible defaults:

bash
owt new "Fix the pagination off-by-one error" --template bugfix
owt new "Add dark mode support" --template feature
owt new "Patch the XSS vulnerability" --template hotfix

Templates configure the worktree setup (branch prefix, AI tool settings, etc.) based on the type of work.

Next Steps ​