Stax
The fastest stacked-branch workflow for Git. Interactive TUI, smart PRs, safe undo. Written in Rust.
Install / Use
/learn @cesarferreira/StaxREADME
Ship small, reviewable PR stacks quickly without giving up safety.
More than stacked branches: stax can merge an entire stack when CI turns green, resolve in-progress rebase conflicts with AI guardrails, run parallel AI worktree lanes as normal tracked branches, and generate PR bodies or standup summaries from the work you actually shipped.
stax installs both binaries: stax and the short alias st. This README uses st.
- Live docs: cesarferreira.github.io/stax
- Docs index in this repo: docs/index.md
Why stax
- Replace one giant PR with a clean stack of small, focused PRs
- Keep shipping while lower-stack PRs are still in review
- Merge from the bottom automatically when PRs are ready, locally or remotely (
st merge --when-ready,st merge --remote) - Resolve in-progress rebase conflicts with AI, limited to the conflicted files (
st resolve) - Recover from risky restacks and rewrites immediately (
st undo,st redo) - Run parallel AI worktree lanes as normal tracked branches (
st wt c ... --agent codex) - Generate PR bodies and spoken standup summaries with your preferred AI agent
- Navigate the full stack and diffs from an interactive TUI
Install
# Homebrew (macOS/Linux)
brew install cesarferreira/tap/stax
# Or cargo-binstall
cargo binstall stax
Prebuilt binaries (no package manager needed)
Download the latest binary from GitHub Releases:
# macOS (Apple Silicon)
curl -fsSL https://github.com/cesarferreira/stax/releases/latest/download/stax-aarch64-apple-darwin.tar.gz | tar xz
# macOS (Intel)
curl -fsSL https://github.com/cesarferreira/stax/releases/latest/download/stax-x86_64-apple-darwin.tar.gz | tar xz
# Linux (x86_64)
curl -fsSL https://github.com/cesarferreira/stax/releases/latest/download/stax-x86_64-unknown-linux-gnu.tar.gz | tar xz
# Move binary to ~/.local/bin and symlink `st` alias
mkdir -p ~/.local/bin
mv stax ~/.local/bin/
ln -s ~/.local/bin/stax ~/.local/bin/st
# If ~/.local/bin is not on your PATH, add it:
# echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # or ~/.bashrc
Windows (x86_64): download stax-x86_64-pc-windows-msvc.zip from GitHub Releases, extract stax.exe, and place it in a directory on your PATH. See Windows notes for shell and worktree limitations.
Verify install:
st --version
<a id="quick-start"></a>
60-Second Quick Start
Set up GitHub auth first (required for PR creation, CI checks, and review metadata).
# Option A (recommended): import GitHub CLI auth
gh auth login
st auth --from-gh
# Option B: enter token interactively
st auth
# Option C: env var
export STAX_GITHUB_TOKEN="ghp_xxxx"
By default, stax does not use ambient GITHUB_TOKEN unless you opt in with auth.allow_github_token_env = true.
# 1. Create stacked branches
st create auth-api
st create auth-ui
# 2. Inspect stack
st ls
# ◉ auth-ui 1↑
# ○ auth-api 1↑
# ○ main
# 3. Submit PRs for whole stack
st ss
# 4. After auth-api PR is merged on GitHub...
# Pull trunk, detect the merge, delete auth-api, reparent auth-ui → main
st rs
# Rebase auth-ui onto updated main
st restack
# Or do both in one shot:
st rs --restack
Result: two stacked branches, submitted as two linked PRs. After the bottom PR is merged, sync detects it, cleans up, and restack rebases the remaining branch onto trunk.
Picked the wrong trunk branch? Run st trunk main to switch it, or st init --trunk <branch> to reconfigure from scratch.
Next steps:
<a id="core-commands"></a>
Core Commands
| Command | What it does |
|---|---|
| st | Launch interactive TUI |
| st ls | Show stack with PR/rebase status |
| st ll | Show stack with PR URLs and details |
| st create <name> | Create a branch stacked on current |
| st ss | Submit full stack and create/update PRs |
| st merge | Merge PRs from stack bottom to current |
| st merge --when-ready | Wait/poll until mergeable, then merge |
| st merge --remote | Merge the stack remotely on GitHub while you keep working locally |
| st rs | Sync trunk and clean merged branches (no rebasing) |
| st rs --restack | Sync trunk, clean merged branches, then rebase stack |
| st restack | Rebase current stack onto parents locally (--stop-here skips descendants) |
| st cascade | Restack, push, and create/update PRs |
| st undo / st redo | Recover or re-apply risky operations |
| st resolve | Resolve an in-progress rebase conflict with AI and continue automatically |
| st standup | Summarize recent engineering activity |
| st pr | Open the current branch PR in the browser |
| st pr list | Show open pull requests in the current repo |
| st issue list | Show open issues in the current repo |
| st generate --pr-body [--no-prompt] | Generate PR body with AI |
| st run <cmd> (alias: st test <cmd>) | Run a command on each branch in stack |
For complete command and flag reference: docs/commands/core.md and docs/commands/reference.md.
Key Capabilities
<a id="cascade-stack-merge"></a>
Cascade Stack Merge
Merge from stack bottom up to your current branch with safety checks for CI/readiness.
# Merge from bottom -> current branch
st merge
# Wait for readiness explicitly before merging
st merge --when-ready
# Merge full stack regardless of current position
st merge --all
Read more: docs/workflows/merge-and-cascade.md
Safe History Rewriting (Undo/Redo)
stax snapshots branch state before destructive operations (restack, submit, reorder) so recovery is immediate when something goes wrong.
st restack
st undo
st redo
Read more: docs/safety/undo-redo.md
AI Conflict Resolution
When a restack or merge stops on a rebase conflict, st resolve sends only the currently conflicted text files to your configured AI agent, applies the returned resolutions, and continues the rebase automatically.
# Resolve the current rebase conflict with your configured AI agent
st resolve
# Or override the agent/model for one run
st resolve --agent codex --model gpt-5.3-codex
If the AI returns invalid output, touches a non-conflicted file, or leaves more conflicts behind than allowed, stax stops and keeps the rebase in progress so you can inspect or continue manually.
Read more: docs/commands/core.md and docs/commands/reference.md
Interactive TUI
Launch with no arguments to browse stacks, inspect the selected branch summary, scroll patches, and run common operations without leaving the terminal.
st
Read more: docs/interface/tui.md
<a id="developer-worktrees"></a>
Developer Worktrees
Work on multiple stacks in parallel without losing context. st worktree (alias st wt) creates and manages Git worktree lanes for existing or new branches, with shell integration for transparent cd.
# Open the worktree dashboard (interactive terminals only)
st wt
# One-time shell integration setup
st shell-setup --install # writes ~/.config/stax/shell-setup.sh and sources it from ~/.zshrc
# Create a fresh random lane or a named lane
st worktree create
st worktree create payments-api
# List all worktrees (* = current)
st worktree list
# Jump to a worktree (transparent cd via shell function)
st worktree go payments-api
# or the quick alias:
sw payments-api
# Remove when done
st worktree remove payments-api
Shortcuts: st w (list), st wtc [branch] (create), st wtgo <name> (go), st wtrm <name> (remove). In an interactive terminal, bare st wt opens the worktree dashboard and uses tmux-backed re-entry for lanes.
Read more: docs/workflows/multi-worktree.md
<a id="worktree-lanes"></a>
Worktree Lanes For AI
Run 2, 3, or 8 AI coding sessions in parallel without sharing one working directory.
Each lane is an isolated Git worktree with a real branch behind it. When stax creates the branch for a lane, it also writes normal stax metadata, so that lane shows up in st ls, participates in restack/sync/undo, and can be reopened instantly with st wt go.
# Spin up three lanes in parallel
st wt c auth-refresh --agent claude -- "fix token refresh edge cases"
st wt c flaky-tests --agent codex -- "stabilize the flaky test suite"
st wt c ui-polish --run "cursor ."
st wt c review-pass --agent codex --tmux -- "address the open PR comments"
# They are normal stax branches, not hidden scratch dirs
st ls
# Trunk moved while they were running? Restack every managed lane
st wt rs
# Jump back into any lane and continue exactly where you left off
st wt go flaky-tests --agent codex
st wt go review-pass --agent codex --tmux
# Rich st
