Configuration

workrex uses a two-level configuration system:

Global (~/.config/workrex/config.yaml): Personal defaults for all projects. Run workrex config edit to open it in your editor.
Project (.workrex.yaml): Project-specific overrides

Project settings override global settings. When you run workrex from a subdirectory, it walks upward to find the nearest .workrex.yaml, allowing nested configs for monorepos. See Monorepos for details. For hook lists (post_create, pre_merge, pre_remove) and file operation lists (files.copy, files.symlink, remote_files.copy, remote_files.symlink), you can use "<global>" to include global values alongside project-specific ones. Other settings like panes are replaced entirely when defined in the project config.

Workrex owns these paths and the WORKREX_* environment variables. Keep project configuration with its repository and personal remotes in global configuration.

XDG Base Directory support

workrex respects the XDG Base Directory Specification:

Purpose	Environment variable	Default
Configuration	`XDG_CONFIG_HOME`	`~/.config`
Cache	`XDG_CACHE_HOME`	`~/.cache`
State	`XDG_STATE_HOME`	`~/.local/state`

All workrex files live under a workrex/ subdirectory within these base directories. If you have an existing config at the default location and later set a custom XDG_CONFIG_HOME, workrex will fall back to reading from ~/.config/workrex/ if no config exists at the new location.

The host-side log lives at $XDG_STATE_HOME/workrex/workrex.log and includes sandbox network-proxy rejections - see Debugging blocked requests.

Global configuration example

~/.config/workrex/config.yaml:

nerdfont: true # Enable nerdfont icons (prompted on first run)
merge_strategy: rebase # Make workrex merge do rebase by default
merge_keep: true # Keep worktree, window, and branch after merge by default
agent: claude

panes:
  - command: <agent> # Start the configured agent (e.g., claude)
    focus: true
  - split: horizontal # Second pane with default shell

Project configuration example

.workrex.yaml:

post_create:
  - "<global>"
  - mise use

files:
  symlink:
    - "<global>" # Include global symlinks (node_modules)
    - .pnpm-store # Add project-specific symlink

panes:
  - command: pnpm install
    focus: true
  - command: <agent>
    split: horizontal
  - command: pnpm run dev
    split: vertical

For a real-world example, see workrex’s own .workrex.yaml.

Configuration options

Most options have sensible defaults. You only need to configure what you want to customize.

Basic options

Option	Description	Default
`main_branch`	Branch to merge into	Auto-detected
`base_branch`	Default base ref for new worktrees, or `auto` for the effective main branch	Current branch
`worktree_dir`	Directory for worktrees (absolute or relative). Supports `~` and `{project}`.	`<project>__worktrees/`
`nerdfont`	Enable nerdfont icons (prompted on first run)	Prompted
`window_prefix`	Override Rex session or window prefix. Supports `{project}`.	Icon or `wr-`
`window_placement`	New Rex window placement (`after_current` or `rightmost`)	`after_current`
`agent`	Default agent for `<agent>` placeholder	`claude`
`agents`	Named agent commands (global-only). See named agents.	`{}`
`prompt_file_only`	Write prompt files without injecting into agent commands	`false`
`merge_strategy`	Default merge strategy (`merge`, `rebase`, `squash`)	`merge`
`merge_keep`	Keep resources after `workrex merge` by default	`false`
`theme`	Dashboard color scheme (see themes)	`default` (auto dark/light)
`mode`	`session` creates a workspace per task; `window` creates a tab in a chosen session. See session mode.	`session`
`default_session`	Session to return to when a workrex session closes (session mode)	Previous session
`stale_after`	Inactivity before an agent counts as stale: seconds, or a duration such as `90m` or `5h`	`1h`
`confirm_unmerged_removal`	Ask before deleting a branch with commits not merged into its base	`true`
`auto_update_check`	Check for a new workrex release in the background	`true`
`placement`	Where `workrex add` creates agents: `local` or a remote name. See remotes.	`local`

Set base_branch: auto to create new branches from the effective main branch, regardless of the currently checked-out branch. Workrex uses configured main_branch, then the local origin/HEAD, main, or master. Detection uses local Git state and does not fetch. An explicit workrex add --base takes precedence. When base_branch is omitted, new branches use the checked-out branch.

Remotes

remotes defines the SSH servers that can run agents. See remote servers for setup and usage.

remotes:
  devbox:
    host: devbox
    path: ~/.workrex-node
    # isolation: container # optional: force Docker regardless of sandbox.enabled

placement: devbox

Option	Description	Default
`remotes.<name>.host`	SSH destination: an alias from `~/.ssh/config` or `user@host`	required
`remotes.<name>.path`	Node root on the remote: `~`, a path starting with `~/` (expanded on the remote), or an absolute path	`~/.workrex-node`
`remotes.<name>.isolation`	`container` forces Docker; `none` forces host execution. See server or Docker	follows `sandbox.enabled`
`remotes.<name>.binary`	Local path to a Linux `workrex` binary to install instead of the matching release. Releases exist for linux-amd64 only, so an ARM64 server needs this	none
`remotes.<name>.terminal`	Terminal host for remote agents; the only supported value is `rex`. See agent terminals on the server’s Rex	`rex`
`remotes.<name>.rex_client`	Label of the Rex.app client `workrex open` switches when several are connected to the server’s Rex server	the only one

remotes is global-only: in a project’s .workrex.yaml it is ignored with a warning. Unknown keys under a remote are an error.

placement sets where workrex add creates agents when neither --remote nor --local is given. It can be set globally or per project; the project value wins. It can only name a remote from the global remotes, and it is ignored when no remotes are configured.

The dashboard and sidebar blocks have their own pages: dashboard configuration and sidebar customization.

Themes

The dashboard supports 12 color schemes, each with dark and light variants. Dark/light mode is auto-detected from your terminal background.

Press T (shift+t) in the dashboard to cycle through schemes. The selection persists to your global config (~/.config/workrex/config.yaml).

Available schemes: default, emberforge, glacier-signal, obsidian-pop, slate-garden, phosphor-arcade, lasergrid, mossfire, night-sorbet, graphite-code, festival-circuit, teal-drift.

# Just a scheme name (auto-detect dark/light)
theme: emberforge

# Force a specific mode
theme:
  scheme: emberforge
  mode: light

Custom colors

You can override individual palette colors using the custom block. Custom colors are applied on top of the base scheme, so you can start from any built-in theme and tweak specific colors. Values can be hex colors ("#51afef"), named colors (red, cyan), or terminal color indices (42):

theme:
  custom:
    bg: "#282c34"
    fg: "#bbc2cf"
    accent: "#51afef"
    success: "#98be65"
    warning: "#ECBE7B"
    error: "#ff6c6b"

You can also combine custom colors with a specific scheme and mode:

theme:
  scheme: emberforge
  mode: dark
  custom:
    accent: "#51afef"
    danger: "#ff6c6b"

Shorthand aliases: bg for current_row_bg, fg for text, error for danger.

All palette fields: current_row_bg, highlight_row_bg, current_worktree_fg, dimmed, text, border, help_border, help_muted, header, keycap, info, success, warning, danger, accent.

Custom colors persist when cycling themes with T.

Naming options

Option	Description	Default
`worktree_naming`	How to derive names from branches	`full`
`worktree_prefix`	Prefix for worktree directories and windows	none

worktree_naming strategies:

full: Use the full branch name (slashes become dashes)
basename: Use only the part after the last / (e.g., prj-123/feature → feature)

Panes

Define your multiplexer pane layout with the panes array. For multiple windows in session mode, use windows instead (they are mutually exclusive).

panes:
  - command: <agent>
    name: agent
    focus: true
  - command: npm run dev
    name: dev
    split: horizontal
    size: 15

Each pane supports:

Option	Description	Default
`command`	Command to run (see agent placeholders below)	Shell
`focus`	Whether this pane receives focus	`false`
`zoom`	Zoom pane to fullscreen (implies `focus: true`)	`false`
`split`	Split direction (`horizontal` or `vertical`)	---
`size`	Absolute size in lines/cells	50%
`percentage`	Size as percentage (1-100)	50%
`target`	0-based pane index to split from; defaults to most recent pane	most recent pane

Use target when a new pane should split from an earlier pane instead of the one that was just created. This is useful for layouts with two panes across the top and one full-width pane on the bottom.

panes:
  - command: nvim
    focus: true
  - command: pnpm install && pnpm run dev
    split: vertical
    size: 15
  - command: <agent>
    split: horizontal
    target: 0

The example places nvim at the top left, the agent to its right, and the dev server across the bottom. target must refer to a pane that already exists in the same layout. For example, pane 2 can target 0 or 1, but not 2 or any later pane.

size sets a split’s extent in terminal cells. percentage sets its share of the Rex layout. Workrex translates the configured split into Rex block layout operations.

Agent placeholders

<agent>: resolves to the configured agent (from agent config or --agent flag)
<agent:name>: resolves to a named agent profile from global config

Named agent profiles can provide structured command, args, env, and type fields, including env values loaded with from_env. See named agents for the full profile schema.

Built-in agents (claude, gemini, agy, codex, opencode, kiro-cli, vibe, pi, omp, grok, muse) are auto-detected when used as literal commands and receive prompt injection automatically, without needing the <agent> placeholder or a matching agent config:

panes:
  - command: "claude --dangerously-skip-permissions"
    focus: true
  - command: "codex --yolo"
    split: vertical

Each agent receives the prompt (via -p/-P/-e) using the correct format for that agent. Auto-detection matches the executable name regardless of flags or path.

Antigravity CLI support covers command detection, prompt injection, and status tracking through lifecycle hooks installed by workrex setup.

Named layouts

Define reusable pane arrangements in the layouts map and select one at add-time with -l/--layout:

layouts:
  design:
    panes:
      - command: <agent>
        focus: true
      - command: <agent:codex>
        split: vertical
  review:
    panes:
      - command: <agent>

workrex add my-feature -l design

When -l is used, the layout’s panes replace the top-level panes for that worktree. All other config (hooks, files, agent, etc.) comes from the top-level as usual. The -l flag cannot be combined with --agent.

Windows

When using session mode, you can configure multiple windows per session using the windows array. This is mutually exclusive with the top-level panes config. See multiple windows per session for full details.

mode: session
windows:
  - name: editor
    panes:
      - command: <agent>
        focus: true
      - split: horizontal
        size: 20
  - name: tests
    panes:
      - command: just test --watch

File operations

New worktrees are clean checkouts with no gitignored files (.env, node_modules, etc.). Use files to automatically copy or symlink what each local worktree needs:

files:
  copy:
    - .env
  symlink:
    - .next/cache # Share build cache across worktrees

Both copy and symlink accept glob patterns.

Remote workspaces use independent remote_files.copy and remote_files.symlink lists, with no fallback to files. By default, only the Git checkout is transferred. Explicitly select any supplemental files you need remotely:

remote_files:
  copy:
    - .env
    - CLAUDE.local.md

These lists follow the same config-relative path and "<global>" merge rules as files. Remote symlink sources are uploaded once and shared, not synchronized. See Remote supplemental files for cache behavior and disabling inherited transfers.

To re-apply file operations to existing worktrees (e.g., after updating the config), use workrex sync-files.

Lifecycle hooks

Run commands at specific points in the worktree lifecycle, such as installing dependencies or running database migrations. All hooks run with the worktree directory as the working directory (or the nested config directory for nested configs) and receive environment variables: WORKREX_HANDLE, WORKREX_WORKTREE_PATH, WORKREX_PROJECT_ROOT, WORKREX_CONFIG_DIR.

hook_shell is an argv list containing the executable followed by its arguments. Workrex appends each hook command as the final argument. It defaults to ["bash", "-c"] for compatibility. To select a specific Bash installation on macOS, set the machine-specific path in your global configuration:

hook_shell: ["/opt/homebrew/bin/bash", "-c"]

A project can override the complete hook_shell argv in .workrex.yaml; when omitted, it inherits the global value. The argv must contain a non-empty executable. Workrex reports the configured executable when it cannot be launched. Shell flags such as error handling or login behavior are applied only when included explicitly in hook_shell or the hook command. Remote workspaces run hooks with bash -c when hook_shell names an absolute path, since that path refers to a local program; see What the server uses from your config.

Hook	When it runs	Additional env vars
`post_create`	After worktree creation, before Rex window opens	-
`pre_merge`	Before merging (aborts on failure)	`WORKREX_BRANCH_NAME`, `WORKREX_TARGET_BRANCH`
`pre_remove`	Before worktree removal (aborts on failure)	-

WORKREX_PROJECT_ROOT points to the repository’s main worktree, regardless of where the selected config is stored. WORKREX_CONFIG_DIR points to the corresponding config directory in the new worktree, which may differ from WORKREX_WORKTREE_PATH when using nested configs.

Example:

post_create:
  - direnv allow

pre_merge:
  - just check

In Node.js projects, pre_remove defaults to a fast node_modules cleanup, and defining your own commands replaces that default. Use "<cleanup-node-modules>" to keep it alongside them:

pre_remove:
  - cp -r test-results/ "$WORKREX_PROJECT_ROOT/artifacts/$WORKREX_HANDLE/"
  - "<cleanup-node-modules>"

Agent status icons

Customize the icons shown in Rex window names:

status_icons:
  working: "🤖" # Agent is processing
  waiting: "💬" # Agent needs input (auto-clears on focus)
  done: "✅" # Agent finished (auto-clears on focus)

You can use style-tag codes for colored icons in the dashboard and sidebar:

status_icons:
  done: "#[fg=#a6e3a1]󰄴#[fg=default]"

Supported style-tag attributes: fg=, bg=, default. Colors can be hex (#a6e3a1), named (red, green, etc.), or indexed (colour196).

Rex program status and hook status are shown in the dashboard and sidebar. Rex renders its own tab status indicator.

Auto-name configuration

Configure LLM-based branch name generation for the --auto-name (-A) flag:

auto_name:
  command: "claude -p" # Use a custom command instead of the inferred default
  model: "gemini-2.5-flash-lite"
  background: true
  system_prompt: "Generate a kebab-case git branch name."

The command used for branch name generation is resolved in this order:

auto_name.command is set: uses that command as-is
agent is a known agent (claude, gemini, agy, codex, opencode, kiro-cli, vibe, pi, omp): uses the agent’s CLI with a fast/cheap model automatically
Neither: falls back to the llm CLI (requires installation)

To override back to llm when an agent is configured, set auto_name.command: "llm".

Option	Description	Default
`command`	Command for branch name generation (overrides agent profile)	Agent profile or `llm` CLI
`model`	LLM model to use with the `llm` CLI (ignored when `command` set)	`llm`’s default
`background`	Always run in background when using `--auto-name`	`false`
`system_prompt`	Custom system prompt for branch name generation	Built-in prompt

See workrex add --auto-name for usage details.

Default behavior

Worktrees are created in <project>__worktrees as a sibling directory to your project by default
If no panes configuration is defined, workrex provides opinionated defaults:
- For projects with a CLAUDE.md file: Opens the configured agent (see agent option) in the first pane, defaulting to claude if none is set.
- For all other projects: Opens your default shell.
- Both configurations include a second pane split horizontally
post_create commands are optional and only run if you configure them

Automatic setup with panes

Use the panes configuration to automate environment setup. Unlike post_create hooks which must finish before the Rex window opens, pane commands execute immediately within the new window.

This can be used for:

Installing dependencies: Run npm install or cargo build in a focused pane to monitor progress.
Starting services: Launch dev servers, database containers, or file watchers automatically.
Running agents: Initialize AI agents with specific context.

Since these run in standard Rex blocks, you can interact with them (check logs, restart servers) just like a normal terminal session.

panes:
  # Pane 1: Install dependencies, then start dev server
  - command: pnpm install && pnpm run dev

  # Pane 2: AI agent
  - command: <agent>
    split: horizontal
    focus: true