The .worktreerc file configures Open Orchestrator's behavior for your project.

File Locations

Open Orchestrator searches for configuration in this order:

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

Complete Reference

#
# Open Orchestrator Configuration
#

# Token budget per tool when scraping pane output
# Default: 8000
tool_token_budget = 8000

# UI theme
# Options: auto, dark, light, dark-ansi, light-ansi
# Default: "auto"
theme = "auto"


[worktree]
# Directory where worktrees will be created (relative to main repo)
# Default: "../"
base_directory = "../"

# Number of days before a worktree is considered stale
# Default: 14
auto_cleanup_days = 14

# Pattern for naming worktree directories
# Available placeholders: {project}, {branch}
# Default: "{project}-{branch}"
naming_pattern = "{project}-{branch}"


[tmux]
# Default pane layout
# Default: "single"
default_layout = "single"

# Automatically start AI tool in the pane
# Default: true
auto_start_ai = true

# Which AI tool to start
# Options: claude, pi, opencode, droid
# Default: "claude"
ai_tool = "claude"

# Session name prefix
# Default: "owt"
session_prefix = "owt"

# Enable mouse support in tmux sessions
# Default: true
mouse_mode = true

# Custom tmux prefix key
# Default: "C-a"
prefix_key = "C-a"


[environment]
# Automatically install dependencies when creating a new worktree
# Default: true
auto_install_deps = true

# Copy .env file from main repo to new worktrees
# Default: true
copy_env_file = true

# Adjust relative paths in copied .env file
# Default: true
adjust_env_paths = true

# Additional configuration files to copy to new worktrees
# Default: []
additional_config_files = []


[sync]
# Default sync strategy
# Options: merge, rebase
# Default: "merge"
default_strategy = "merge"

# Automatically stash changes before syncing
# Default: true
auto_stash = true

# Prune remote-tracking branches during sync
# Default: true
prune_remote = true


[claude]
# Claude Code specific settings

# Note: Pi has no config section -- it launches as a bare `pi`


[opencode]
# Path to OpenCode configuration file
# Default: null
config_path = "~/.config/opencode/opencode.json"


[droid]
# Default autonomy level for Droid
# Options: low, medium, high
# Default: null (use Droid's default)
default_auto_level = "medium"

# Skip permissions check (DANGEROUS)
# Default: false
skip_permissions_unsafe = false


[backend]
# Multiplexer backend
# Options: tmux (default), herdr
# Default: "tmux"
type = "tmux"


# Custom AI tool registration
# Define as [tools.NAME] sections

[tools.mytool]
binary = "my-ai-tool"
command_template = "{binary} --interactive"
prompt_flag = "-p"
supports_hooks = false
install_hint = "Install from https://example.com/mytool"
known_paths = ["~/.local/bin/mytool"]


# Custom templates
# Define as [templates.NAME] sections

[templates.tdd-feature]
name = "tdd-feature"
description = "Feature development with TDD"
base_branch = "develop"
ai_tool = "claude"
plan_mode = true
install_deps = true
tmux_layout = "single"
auto_commands = ["uv run pre-commit install"]
tags = ["backend", "tdd"]
ai_instructions = """
Follow test-driven development:
1. Write failing test
2. Make it pass
3. Refactor
"""

Section Details

Top-Level Settings

Option	Type	Default	Description
tool_token_budget	int	8000	Token budget per tool when scraping pane output
theme	string	"auto"	UI theme: auto, dark, light, dark-ansi, light-ansi

[worktree]

Controls how worktrees are created and named.

Option	Type	Default	Description
base_directory	string	"../"	Where to create worktrees
auto_cleanup_days	int	14	Days until considered stale
naming_pattern	string	"{project}-{branch}"	Directory naming pattern

Naming pattern placeholders:

• {project} - Project name (directory name of main repo)
• {branch} - Branch name (with / replaced by -)

[tmux]

Controls tmux session creation and behavior.

Option	Type	Default	Description
default_layout	string	"single"	Default pane layout
auto_start_ai	bool	true	Start AI tool automatically
ai_tool	string	"claude"	Which AI tool to start
session_prefix	string	"owt"	Prefix for tmux session names
mouse_mode	bool	true	Enable tmux mouse support
prefix_key	string	"C-a"	tmux prefix key

[environment]

Controls environment setup for new worktrees.

Option	Type	Default	Description
auto_install_deps	bool	true	Install dependencies
copy_env_file	bool	true	Copy .env file
adjust_env_paths	bool	true	Adjust paths in .env
additional_config_files	array	[]	Extra files to copy

[sync]

Controls sync behavior for keeping worktrees up to date.

Option	Type	Default	Description
default_strategy	string	"merge"	Sync strategy: merge or rebase
auto_stash	bool	true	Stash changes before syncing
prune_remote	bool	true	Prune stale remote branches

[claude]

Claude Code specific settings. This section is reserved for Claude-specific configuration that may be added in future versions.

Pi has no config section. It launches as a bare pi and submits prompts interactively via Enter, so no tool-specific settings are needed -- just set ai_tool = "pi" under [tmux].

[opencode]

OpenCode-specific settings.

Option	Type	Default	Description
config_path	string	null	Path to OpenCode config file

[droid]

Droid-specific settings.

Option	Type	Default	Description
default_auto_level	string	null	Autonomy: low, medium, high
skip_permissions_unsafe	bool	false	Skip permissions check

[backend]

Selects the multiplexer backend that drives worktree sessions.

Option	Type	Default	Description
type	string	"tmux"	Multiplexer backend: tmux or herdr

The default tmux backend works everywhere tmux is installed. The herdr backend is an opt-in alternative -- see Backends for details.

[tools.NAME]

Custom AI tool definitions. See Custom Tool Registration for the full option reference.

[templates.NAME]

Custom template definitions. Each template is a TOML table under [templates].

Option	Type	Description
name	string	Unique template identifier
description	string	Short description
base_branch	string	Branch to branch from (e.g., main, develop)
ai_tool	string	AI tool: claude, pi, opencode, droid
plan_mode	boolean	Start AI in plan mode
install_deps	boolean	Install dependencies on creation
tmux_layout	string	Pane layout for the session
auto_commands	array	Commands to run automatically after setup
tags	array	Labels for organizing templates
ai_instructions	string	Instructions to provide to the AI tool

Example Configurations

Python Project with uv

[worktree]
base_directory = "../worktrees"
naming_pattern = "myproject-{branch}"
auto_cleanup_days = 7

[tmux]
ai_tool = "claude"
auto_start_ai = true

[environment]
auto_install_deps = true
copy_env_file = true

Node.js Frontend Project

[worktree]
base_directory = "../"
naming_pattern = "frontend-{branch}"

[tmux]
ai_tool = "claude"
auto_start_ai = true

[environment]
auto_install_deps = true
copy_env_file = true

Minimal Configuration

[worktree]
auto_cleanup_days = 7

[tmux]
ai_tool = "claude"

Multi-Tool Team Configuration

[tmux]
ai_tool = "claude"
auto_start_ai = true

[droid]
default_auto_level = "medium"
skip_permissions_unsafe = false

[opencode]
config_path = "~/.config/opencode/opencode.json"

[templates.backend]
name = "backend"
description = "Backend feature with Claude"
base_branch = "develop"
ai_tool = "claude"
plan_mode = true
ai_instructions = "Follow RESTful API design. Write tests first."

[templates.automated-refactor]
name = "automated-refactor"
description = "Automated refactoring with Droid"
base_branch = "develop"
ai_tool = "droid"
plan_mode = false
ai_instructions = "Refactor for readability. Keep all tests passing."

See Also

• AI Tool Settings
• Environment Setup
• Templates