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.

For a comprehensive example configuration file with comments explaining all options, see the example_config.toml in the repository.

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:

1. Built-in Defaults: Sensible defaults for all settings.
2. Global config.toml: User-wide settings that apply to all your projects.
3. Project .autowt.toml: Project-specific settings, defined in your repository's root.
4. Environment Variables: System-wide overrides, prefixed with AUTOWT_.
5. 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 a .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.

[worktree] - Worktree management¶

Defines how worktrees are created and managed.

[cleanup] - Cleanup behavior¶

Configures the autowt cleanup command.

[scripts] - Lifecycle hooks and scripts¶

See Lifecycle Hooks.

[scripts.custom]¶

Define named, reusable scripts for specialized workflows. Custom scripts can be simple command strings or full workflow profiles with their own lifecycle hooks and dynamic branch naming.

Simple format¶

The simplest form is a command string that runs as session_init. For simple format scripts, the first CLI argument is used as the branch name:

[scripts.custom]
# Simple: just a session_init command
# First argument ($1) becomes the branch name
bugfix = 'claude "Fix the bug described in GitHub issue $1"'

Usage: awt bugfix 123 creates a branch named 123 with the session_init command.

Enhanced format¶

For more control, use a nested table to define a complete workflow profile:

[scripts.custom.ghllm]
# Help text for --help output
description = "Create worktree from GitHub issue"

# Dynamic branch name from command output
branch_name = "gh issue view $1 --json title --template '{{.title}}'"

# Hook inheritance (default: true)
inherit_hooks = true

# Any lifecycle hook can be overridden
pre_create = "echo 'Starting ghllm workflow'"
session_init = 'claude "Work on GitHub issue $1"'

Custom script fields¶

Argument interpolation¶

All string fields support $1, $2, $3, etc. placeholders that are replaced with arguments passed to the custom script:

# Invoke custom script directly (recommended)
awt ghllm 123

# Or using the legacy flag
awt --custom-script="ghllm 123"

# $1 is replaced with "123" in all fields

Dynamic branch naming¶

When branch_name is set, the command is executed and its stdout becomes the branch name. The output is automatically normalized to be a valid git ref:

• Converted to lowercase
• Spaces and underscores become dashes
• Invalid git ref characters are removed
• Double dots, consecutive dashes/slashes are collapsed

Example transformations:

Hook inheritance¶

When inherit_hooks = true (the default), hooks run in this order:

1. Global config hook (if defined)
2. Project config hook (if defined)
3. Custom script hook (if defined)

When inherit_hooks = false, only the custom script's hooks run; global and project hooks are skipped.

Example workflows¶

GitHub issue workflow - Creates a branch named after the issue title:

[scripts.custom.ghissue]
branch_name = "gh issue view $1 --json title --template '{{.title}}'"
session_init = 'claude "Work on GitHub issue $1: $(gh issue view $1 --json title --template '\''{{.title}}'\'')"'

Release workflow - Custom pre_create and session_init:

[scripts.custom.release]
inherit_hooks = false  # Skip normal hooks
pre_create = "git fetch --tags"
session_init = 'claude "/release"'

Custom scripts are invoked directly as subcommands:

# Enhanced format (branch_name field) - issue number is an argument
awt ghissue 123

# Simple format - first argument is used as the branch name
awt release release-v2.0

Resolution priority: When autowt receives an unknown command, it checks in this order:

1. Built-in commands (ls, cleanup, config, switch, and their aliases)
2. Custom scripts (matches against [scripts.custom] names)
3. Branch names (treats the command as a branch to switch to)

If you have a custom script named main and want to switch to a branch named main, use awt switch main to force branch interpretation.

[confirmations] - User interface¶

Manage which operations require a confirmation prompt.

You can skip all confirmations for a single command by using the -y or --yes flag.