Open Orchestrator automatically sets up the development environment when creating worktrees. This page covers how to configure and customize this behavior.

Automatic Setup

By default, when you create a worktree with owt new "task", Open Orchestrator:

1. Detects your project type
2. Installs dependencies using the detected package manager
3. Copies environment files (.env)
4. Adjusts relative paths in copied files

Configuration

Basic Settings

[environment]
auto_install_deps = true
copy_env_file = true
adjust_env_paths = true
additional_config_files = []

Disable Automatic Setup

# Skip dependency installation
owt new "Quick experiment" --no-deps

Project Detection

Open Orchestrator automatically detects project types:

Project Type	Detection Files	Package Managers
Python	pyproject.toml, requirements.txt, uv.lock	uv, poetry, pipenv, pip
Node.js	package.json, bun.lockb, pnpm-lock.yaml	bun, pnpm, yarn, npm
Rust	Cargo.toml	cargo
Go	go.mod	go
PHP	composer.json	composer

Package Manager Priority

When multiple package managers are available, Open Orchestrator uses this priority:

Python:

1. uv (if uv.lock or uv installed)
2. poetry (if poetry.lock)
3. pipenv (if Pipfile.lock)
4. pip (fallback)

Node.js:

1. bun (if bun.lockb)
2. pnpm (if pnpm-lock.yaml)
3. yarn (if yarn.lock)
4. npm (fallback)

Override Detection

Force a specific project type:

[project]
type = "python"
package_manager = "uv"
install_command = "uv sync --dev"

Dependency Installation Commands

Default Commands

Project Type	Package Manager	Command
Python	uv	uv sync
Python	poetry	poetry install
Python	pipenv	pipenv install
Python	pip	pip install -r requirements.txt
Node.js	bun	bun install
Node.js	pnpm	pnpm install
Node.js	yarn	yarn install
Node.js	npm	npm install
Rust	cargo	cargo build
Go	go	go mod download
PHP	composer	composer install

Custom Install Command

Override the install command:

[project]
install_command = "uv sync --dev && uv run pre-commit install"

Environment Files

.env File

By default, .env is copied from the main repo to the new worktree:

[environment]
copy_env_file = true
adjust_env_paths = true

Path Adjustment

When adjust_env_paths = true, relative paths in .env are adjusted:

# Main repo .env
DATABASE_PATH=./data/db.sqlite

# Worktree .env (auto-adjusted)
DATABASE_PATH=../main-repo/data/db.sqlite

Additional Config Files

Copy additional configuration files to new worktrees:

[environment]
additional_config_files = [".env.local", ".env.development"]

Disable Path Adjustment

[environment]
adjust_env_paths = false

Then manage paths manually in your .env files.

Environment Variables

Open Orchestrator uses several environment variables for coordination between the CLI, orchestrator, and AI agents:

Variable	Set By	Purpose
OWT_AUTOMATED	OWT (orchestrated panes)	Marks panes as automated; used by hooks to distinguish orchestrated agents from interactive sessions
OWT_WORKTREE_NAME	OWT (all panes)	Current worktree name; used by MCP peer communication and hooks
OWT_DB_PATH	User override or OWT	Points all components to the same SQLite status database
OWT_BACKGROUND	Auto-detected or user	Terminal background hex color for the Control Plane / UI

Using OWT_AUTOMATED in Hooks

The OWT_AUTOMATED variable lets you write hooks that behave differently in orchestrated vs. interactive sessions:

#!/bin/bash
# Example: skip interactive confirmation in automated panes
if [ -n "$OWT_AUTOMATED" ]; then
  # Running under orchestrator -- non-interactive
  exit 0
fi
# Interactive session -- prompt user

Overriding the Database Path

By default, the status database lives at ~/.open-orchestrator/status.db. Override this to share a database across environments or use a project-local database:

export OWT_DB_PATH=/path/to/project/status.db

Troubleshooting

Dependencies Not Installing

1. Check project detection by creating a test worktree:

   owt new "Test config" --verbose

2. Verify package manager:

   which npm  # or uv, pip, etc.

3. Install manually in the worktree directory.

Wrong Package Manager Detected

Override in config:

[project]
package_manager = "pnpm"

.env Not Copied

1. Verify .env exists in main repo
2. Check configuration:

   [environment]
   copy_env_file = true

Best Practices

1. Use Lock Files

Ensure reproducible environments:

• Python: uv.lock or poetry.lock
• Node.js: package-lock.json, yarn.lock, or pnpm-lock.yaml

2. Keep .env.example Updated

Maintain a template for environment files:

cp .env.example .env

3. Use Custom Install for Complex Projects

[project]
install_command = """
npm install
npm run setup
npm run db:migrate
"""

4. Test Your Configuration

Create a test worktree to verify:

owt new "Test configuration"
# Verify everything works
owt delete test/configuration --yes

See Also

• .worktreerc Reference
• Project Detection