Worktrees¶

stax has two related worktree stories:

• Repo-wide awareness — restack, sync, cascade, and metadata operations run in the right linked checkout automatically. See Multi-worktree behavior.
• The st worktree command family — create, enter, inspect, and clean up worktree lanes. This page is the canonical guide.

For the parallel AI workflow built on top, see AI worktree lanes.

Quick start¶

# Open the interactive dashboard
st wt

# Create a fresh lane with a random name
st wt c

# Create or reuse a named lane
st wt c payments-api

# Start a new lane from an explicit base
st wt c payments-api --from main

# Jump back into a lane
st wt go payments-api

# Inventory
st wt ls
st wt ll

# Print the absolute path (scripting)
st wt path payments-api

# Remove / clean up
st wt rm payments-api
st wt cleanup --dry-run
st wt prune
st wt rs

How create and go resolve targets¶

st wt c [name] is convenience-first:

• no name → random two-word lane slug
• name matches an existing worktree → reuse it
• name matches an existing branch → create a worktree for that branch
• otherwise → create a new branch and a new worktree

st wt go [name] only opens existing worktrees. With no name, it opens a picker.

Selectors accepted by go, path, rm, and reuse paths in create:

• worktree name
• full branch name
• unique branch suffix (e.g. payments-api matching cesar/payments-api)
• absolute worktree path

Base branch rules for new lanes¶

• --from <branch> explicitly sets the base
• otherwise if the current branch is tracked by stax → new lane stacks on current
• otherwise → new lane starts from trunk

--pick chooses an existing local branch interactively. --name <label> lets the worktree directory label differ from the branch name. --no-verify skips worktree hooks for that command.

Command map¶

Launch other tools inside a lane¶

st wt c ui-polish  --run "cursor ."
st wt c review-pass --agent codex --tmux -- "address the open PR comments"
st wt go review-pass --agent codex --tmux

• --agent supports claude, codex, gemini, opencode
• --model requires --agent
• --run and --agent are mutually exclusive
• anything after -- is passed through to the agent/command
• --tmux creates/reuses a session named after the worktree unless --tmux-session overrides

If you run create / go without shell integration and without a launcher, stax prints the cd command to copy.

Managed vs unmanaged¶

st wt ls shows every Git worktree, including ones created outside stax. The important distinction is whether the branch has stax metadata:

• new branches created by st wt c foo → managed
• existing tracked branches opened as lanes → stay managed
• existing plain Git branches opened as worktrees → unmanaged until st branch track

Managed lanes behave like first-class stax branches: they show in st ls, participate in restack/sync/undo, and are targeted by st wt restack. Unmanaged lanes still show up in ls, ll, go, rm, and prune, but stax keeps history-rewriting operations conservative.

Dashboard¶

Run st wt in an interactive terminal.

• Left pane: all Git worktrees, including unmanaged
• Right pane: branch, base, path, status, tmux session details

The dashboard is a control plane, not an embedded shell. The stack/patch TUI is documented separately in Interactive TUI.

Shell integration¶

st setup is the one-shot onboarding command for shell integration, AI skills, and auth:

st setup                    # full interactive onboarding
st setup --yes              # accept defaults, install skills, import auth from gh
st setup --install-skills   # install shell integration + skills without prompting
st setup --skip-skills      # install shell integration without the skills prompt
st setup --auth-from-gh     # install shell integration and import auth from gh
st setup --skip-auth        # install shell integration without auth onboarding
st setup --print            # print the snippet for manual install

After installation:

• st wt c ... moves the parent shell into the new lane
• st wt go ... moves the parent shell into the selected lane
• st lane ... moves the parent shell into the selected lane
• st wt rm (no arg) can relocate the shell before removing the current worktree
• sw <name> becomes a quick alias for st wt go <name>

Supports bash, zsh, and fish.

Cleanup and safety¶

cleanup is intentionally conservative. It only targets:

• detached worktrees
• stax-managed worktrees whose branches are already merged into trunk

It skips worktrees that are current, locked, mid-rebase, mid-merge, in conflict, or dirty (unless -f/--force). Use --dry-run to preview and --yes for non-interactive runs.

Location, config, and hooks¶

By default, managed worktrees live outside the repository at:

~/.stax/worktrees/<repo>

Override in ~/.config/stax/config.toml:

[worktree]
# root_dir = ""             # default external root
# root_dir = ".worktrees"   # keep worktrees inside the repo

[worktree.hooks]
post_create = ""   # blocking hook before launch
post_start  = ""   # background hook after creation
post_go     = ""   # background hook after entering an existing worktree
pre_remove  = ""   # blocking hook before removal
post_remove = ""   # background hook after removal

• Relative root_dir values resolve under the main repo root.
• Repo-local roots like .worktrees are added to .gitignore automatically.
• post_create and pre_remove are blocking; post_start, post_go, post_remove run in the background.
• --no-verify on create / go skips hooks for that command.

For the full config surface, see Configuration.