Open Orchestrator

Appearance

This page covers common issues and their solutions.

Installation Issues ​

Command Not Found ​

bash: owt: command not found

Solutions:

  1. Ensure installation completed:

    bash
    pip show open-orchestrator

  2. Check PATH:

    bash
    echo $PATH

  3. Reinstall:

    bash
    pip install -e .

  4. Use full path:

    bash
    python -m open_orchestrator.cli --help

Python Version Error ​

ERROR: Requires Python >= 3.10

Solution: Install Python 3.10+:

bash
# macOS
brew install [email protected]

# Ubuntu
sudo apt install python3.10

Worktree Issues ​

Branch Already Checked Out ​

Error: Branch 'feat/auth' is already checked out at '../other-worktree'

Solutions:

  1. Use a different task description (generates a different branch name):

    bash
    owt new "Add OAuth authentication v2"

  2. Delete existing worktree:

    bash
    owt delete feat/auth
owt new "Add user authentication"

Worktree Path Exists ​

Error: Path '../my-app-feat-auth' already exists

Solutions:

  1. Use force:

    bash
    owt new "Add user authentication" --force

  2. Remove existing directory:

    bash
    rm -rf ../my-app-feat-auth

Not a Git Repository ​

Error: Not a git repository

Solution: Ensure you're in a git repository:

bash
git status
# If not initialized:
git init

Stale Worktree Entries ​

Git worktree list shows entries that don't exist:

bash
git worktree prune

tmux Issues ​

Session Not Found ​

Error: tmux session 'owt-feat-auth' not found

Solutions:

  1. Check available sessions:

    bash
    tmux ls
owt list

  2. Open the Control Plane to see active worktrees:

    bash
    owt

tmux Not Installed ​

Error: tmux command not found

Solution: Install tmux:

bash
# macOS
brew install tmux

# Ubuntu
sudo apt install tmux

Cannot Attach ​

Error: Cannot attach to session from inside tmux

Solution: Detach first with Ctrl+B, D, then attach. Or use the Control Plane (owt) which handles session switching automatically.

AI Tool Issues ​

AI Tool Not Starting ​

Solutions:

  1. Verify tool is installed:

    bash
    which claude
which opencode
which droid

  2. Attach to the worktree session from the Control Plane to see error messages.

  3. Check your .worktreerc configuration.

Wrong Tool Started ​

Solutions:

  1. Use the AI tool picker (Alt+c) to switch tools.

  2. Or kill and restart manually:

    • Attach to the session from the Control Plane
    • Press Ctrl+C to stop current tool
    • Start correct tool manually

Commands Not Being Received ​

Solutions:

  1. Verify the worktree session exists:

    bash
    owt list
tmux ls

  2. Try manual send:

    bash
    tmux send-keys -t owt-feat-auth:0.0 "hello" Enter

Long Prompts Truncated in Orchestrated Sessions ​

If orchestrated or batch agents receive incomplete prompts (especially structured session-init protocols with project context), this was a known issue with tmux send-keys -l which has a ~2K character buffer limit.

Solution: This is now fixed — orchestrated and batch agents use tmux paste-buffer for prompt delivery, which handles arbitrarily long text. If you're still seeing truncation on an older version, update Open Orchestrator.

Status Issues ​

Status Not Updating ​

Solutions:

  1. Check the status file exists:

    bash
    ls -la ~/.open-orchestrator/status.db

  2. Verify worktrees are tracked:

    bash
    owt list

Control Plane Shows No Data ​

Solutions:

  1. Check worktrees exist:

    bash
    owt list

  2. Verify status file:

    bash
    ls -la ~/.open-orchestrator/

Dependency Issues ​

Dependencies Not Installing ​

Solutions:

  1. Check project detection:

    bash
    owt new "Test config" --verbose

  2. Verify package manager:

    bash
    which npm  # or pip, uv, etc.

  3. Install manually in the worktree directory.

  4. Check config override:

    toml
    [project]
package_manager = "npm"

Wrong Package Manager ​

Solution: Override in config:

toml
[project]
type = "node"
package_manager = "pnpm"

Configuration Issues ​

Config Not Loading ​

Solutions:

  1. Check file exists:

    bash
    ls -la .worktreerc

  2. Validate TOML syntax:

    bash
    python -c "import toml; toml.load('.worktreerc')"

  3. Check location priority:

    • .worktreerc in project
    • .worktreerc.toml in project
    • ~/.config/open-orchestrator/config.toml
    • ~/.worktreerc

Settings Not Applied ​

Solution: Configuration changes only apply to newly created worktrees:

bash
# Config changes only apply to new worktrees
owt new "Test new config"

Getting Help ​

If issues persist:

  1. Check verbose output:

    bash
    owt new "Test" --verbose

  2. Review logs:

    bash
    cat ~/.open-orchestrator/*.log

  3. Report an issue

See Also ​