Configuring autowt
autowt is designed to work out of the box with sensible defaults, but you can customize its behavior to perfectly match your workflow. This guide covers the different ways you can configure autowt, from global settings to project-specific rules and one-time command-line overrides.
Configuration layers
autowt uses a hierarchical configuration system. Settings are loaded from multiple sources, and later sources override earlier ones. The order of precedence is:
- Built-in Defaults: Sensible defaults for all settings.
- Global
config.toml: User-wide settings that apply to all your projects. - Project
autowt.toml: Project-specific settings, defined in your repository's root. - Environment Variables: System-wide overrides, prefixed with
AUTOWT_. - Command-Line Flags: The highest priority, for on-the-fly adjustments.
Configuration files
Global configuration
Your global settings are stored in a config.toml file in a platform-appropriate directory:
- macOS:
~/Library/Application Support/autowt/config.toml - Linux:
~/.config/autowt/config.toml(or$XDG_CONFIG_HOME/autowt/config.toml) - Windows:
~/.autowt/config.toml
The easiest way to manage common settings is with the autowt config command, which launches an interactive TUI (Text-based User Interface) for the most frequently used options. For the complete set of configuration options, you can edit the config file directly.
Project-specific configuration
For settings that should apply only to a specific project, create an autowt.toml or .autowt.toml file in the root of your repository. This is the ideal place to define project-wide init scripts or worktree settings.
All configuration options
This section provides a comprehensive reference for all available configuration options, organized by section. Each option includes its TOML key, the corresponding environment variable, and any command-line flags.
[terminal] - Terminal management
Controls how autowt interacts with your terminal.
| Key | Type | Default | Description |
|---|---|---|---|
mode |
string | "tab" |
Determines how autowt opens worktrees. • tab: Open in a new tab (default). • window: Open in a new window. • inplace: Switch the current terminal to the worktree directory. • echo: Output shell commands for shell integration. ENV: AUTOWT_TERMINAL_MODE CLI: --terminal <mode> |
always_new |
boolean | false |
If true, always creates a new terminal session instead of switching to an existing one for a worktree. ENV: AUTOWT_TERMINAL_ALWAYS_NEW CLI: --ignore-same-session |
program |
string | null |
Force autowt to use a specific terminal program instead of auto-detecting one. Examples: iterm2, terminal, tmux ENV: AUTOWT_TERMINAL_PROGRAM |
[worktree] - Worktree management
Defines how worktrees are created and managed.
| Key | Type | Default | Description |
|---|---|---|---|
directory_pattern |
string | "../{repo_name}-worktrees/{branch}" |
The template for creating worktree directory paths. Can use variables {repo_dir} (full repo path), {repo_name} (repo directory name), {repo_parent_dir} (parent directory of repo), {branch} (branch name), and environment variables like $HOME. Examples: "{repo_parent_dir}/worktrees/{branch}", "$HOME/worktrees/{repo_name}/{branch}". ENV: AUTOWT_WORKTREE_DIRECTORY_PATTERN |
max_worktrees |
integer | null |
The maximum number of worktrees allowed per repository. Helps prevent excessive disk usage. ENV: AUTOWT_WORKTREE_MAX_WORKTREES |
auto_fetch |
boolean | true |
If true, automatically fetches from the remote before creating new worktrees. ENV: AUTOWT_WORKTREE_AUTO_FETCH CLI: --no-fetch (to disable) |
default_remote |
string | "origin" |
The default remote to use when multiple remotes exist. ENV: AUTOWT_WORKTREE_DEFAULT_REMOTE |
[worktree.branch_sanitization]
Rules for converting git branch names into safe directory names.
| Key | Type | Default | Description |
|---|---|---|---|
replace_chars |
string | "/:#@^~" |
A string of characters to be replaced with underscores in the directory name. ENV: AUTOWT_WORKTREE_BRANCH_SANITIZATION_REPLACE_CHARS |
max_length |
integer | 255 |
The maximum allowed length for the sanitized directory name. ENV: AUTOWT_WORKTREE_BRANCH_SANITIZATION_MAX_LENGTH |
lowercase |
boolean | false |
If true, converts the entire directory name to lowercase. ENV: AUTOWT_WORKTREE_BRANCH_SANITIZATION_LOWERCASE |
[cleanup] - Cleanup behavior
Configures the autowt cleanup command.
| Key | Type | Default | Description |
|---|---|---|---|
kill_processes |
boolean | true |
If true, automatically kills processes running in a worktree's directory before cleanup. ENV: AUTOWT_CLEANUP_KILL_PROCESSES CLI: --kill / --no-kill |
kill_process_timeout |
integer | 10 |
The timeout in seconds to wait when killing processes. ENV: AUTOWT_CLEANUP_KILL_PROCESS_TIMEOUT |
default_mode |
string | "interactive" |
The default mode for the cleanup command. • interactive: (Default in a TTY) Opens a TUI to let you choose what to remove. • merged: Selects branches that have been merged into your main branch. • remoteless: Selects local branches that don't have an upstream remote. • all: Non-interactively selects all merged and remoteless branches. ENV: AUTOWT_CLEANUP_DEFAULT_MODE CLI: --mode <mode> |
[scripts] - Init scripts and hooks
Automate setup tasks with scripts.
| Key | Type | Default | Description |
|---|---|---|---|
init |
string | null |
A command or script to run automatically after creating or switching to a worktree. See the Init Scripts guide for examples. ENV: AUTOWT_SCRIPTS_INIT CLI: --init "<command>" |
[scripts.custom]
Define named, reusable scripts for specialized workflows.
[scripts.custom]
# Example: autowt my-branch --custom-script="bugfix"
bugfix = 'claude "Fix the bug described in GitHub issue $1"'
# Example: autowt release-branch --custom-script="release"
release = 'claude "/release"'
These are run after the standard init script. You can invoke them with the --custom-script flag, and any additional arguments are passed to the script. For one-time commands, the --after-init flag is often simpler.
[confirmations] - User interface
Manage which operations require a confirmation prompt.
| Key | Type | Default | Description |
|---|---|---|---|
cleanup_multiple |
boolean | true |
Ask for confirmation before cleaning up multiple worktrees in non-interactive mode. ENV: AUTOWT_CONFIRMATIONS_CLEANUP_MULTIPLE |
kill_process |
boolean | true |
Ask for confirmation before killing processes during cleanup. ENV: AUTOWT_CONFIRMATIONS_KILL_PROCESS |
force_operations |
boolean | true |
Ask for confirmation when using a --force flag. ENV: AUTOWT_CONFIRMATIONS_FORCE_OPERATIONS |
You can skip all confirmations for a single command by using the -y or --yes flag.