stax

Stacked Git branches and PRs — fast, safe, and built for humans and AI agents.

Install  ·  Quickstart  ·  Commands  ·  Docs

One giant PR is slow to review and risky to merge. A stack of small PRs is the answer — but managing stacks by hand with git rebase --onto is a footgun. stax makes stacks a first-class Git primitive.

• Stack, don't wait. Keep shipping on top of in-review PRs. st create, st ss, done.
• Native-fast. A single Rust binary that starts in ~25ms. st ls benches ~70× faster than Graphite and ~215× faster than Freephite on this repo.
• Agent-native. Run parallel AI agents on isolated branches (st lane), auto-resolve rebase conflicts (st resolve), and generate branch names, commit messages, and PR details from real diffs.
• GitHub-native stacks, automatically. When your repo has GitHub's native Stacked PRs enabled and github/gh-stack is installed, st ss registers the stack with GitHub under the hood — zero config, zero extra commands. See Native GitHub Stacked PRs.
• Undo-first. Every destructive op snapshots state. st undo / st redo rescue risky rebases instantly.
• Batteries-included TUI. Run bare st to browse the stack, inspect diffs, and watch CI hydrate live.

stax installs two binaries: stax and the short alias st. This README uses st.

The shortest path on macOS and Linux:

brew install cesarferreira/tap/stax

cargo binstall stax

# 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
# Linux (arm64)
curl -fsSL https://github.com/cesarferreira/stax/releases/latest/download/stax-aarch64-unknown-linux-gnu.tar.gz | tar xz

mkdir -p ~/.local/bin
mv stax st ~/.local/bin/
# Ensure ~/.local/bin is on your PATH:
# echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

cargo install --path . --locked
# or
make install

cargo install --path . --locked --features vendored-openssl

Verify the install:

st --version

One-liner:

curl -fsSL https://cesarferreira.com/stax/install-gui.sh | sh

Manual install: download the architecture-specific app from the same GitHub Release as the CLI. For Apple Silicon:

curl -fLO https://github.com/cesarferreira/stax/releases/latest/download/Stax-aarch64-apple-darwin.zip
ditto -x -k Stax-aarch64-apple-darwin.zip .
mv Stax.app /Applications/

On an Intel Mac, use Stax-x86_64-apple-darwin.zip instead. The app is a separate release artifact, not a new crates.io package, and installing it does not enlarge the stax or st CLI binaries.

Ad-hoc-signed releases are supported. Download only from the project Releases page, move the app to /Applications, and try to open it once. Then use System Settings → Privacy & Security → Open Anyway for Stax, authenticate, and confirm Open. The override is available for about an hour after the blocked launch. Do not disable Gatekeeper globally. Releases open normally when the optional signing and notarization credentials are configured.

Contributors can also build or install the app locally:

make gui-app           # Build target/gui-app/Stax.app
make install-gui-app   # Build and install $HOME/Applications/Stax.app
st gui [path]          # Launch a fresh Stax.app instance for one repository

The bundle id is com.cesarferreira.stax. st gui [path] is macOS-only; it canonicalizes the supplied path, defaults to the current directory when omitted, and launches LaunchServices as open -n -b com.cesarferreira.stax --args <canonical-path>. The -n flag is intentional: every invocation starts a fresh app process/window for exactly one repository.

st setup handles shell integration, AI agent skills, and GitHub auth in a single step. When you install skills interactively (or with --yes), stax asks which agent harnesses should receive the skill file, pre-checking the ones it detects on disk. Use --skills all|detected|<ids> for non-interactive control.

st setup --yes

# Import from GitHub CLI
gh auth login && st auth --from-gh

# Enter a token interactively
st auth

# Or via env var
export STAX_GITHUB_TOKEN="ghp_xxxx"

Now ship a two-branch stack end-to-end:

# 1. Stack two branches on trunk
st create auth-api
st create auth-ui

# 2. See the stack
st ls
# ◉  auth-ui        1↑
# ○  auth-api       1↑
# ○  main

# 3. Submit the whole stack as linked PRs
st ss

# 4. After the bottom PR merges on GitHub…
st refresh         # sync trunk, restack this stack, update PRs (`st update` is a back-compat alias)

Picked the wrong trunk? Run st trunk main or st init --trunk <branch> to reconfigure.

Next: Quick Start guide · Merge & cascade workflow

Spin up multiple AI agents on isolated branches, all tracked as normal stax branches:

st lane fix-auth-refresh "Fix the token refresh edge case from #142"
st lane stabilize-ci     "Stabilize the 3 flaky tests in the checkout flow"
st lane api-docs         "Update API docs for the /users endpoint"

Each lane is a real Git worktree with normal stax metadata — it appears in st ls, participates in restack/sync/undo, and re-attaches via tmux any time. No hidden scratch directories, no lost work.

st wt         # open the worktree dashboard
st wt rs      # restack every lane at once when trunk moves
st wt promote # move the current lane branch back to the main worktree
st ss         # submit PRs for the ones that are ready

Lanes start warm: instead of deleting a removed worktree, stax parks it as a reusable warm slot (resetting it to trunk and running git clean -fd, which keeps gitignored dependency directories like node_modules or .venv). The next lane adopts that slot instead of a cold checkout, so agents keep their built deps and don't re-install from scratch. Set worktree.reconcile to re-sync deps on adopt, or worktree.reuse_slots = false to opt out.

→ Agent worktrees · Multi-worktree workflow

When a GitHub repo has native Stacked PRs enabled, stax can register your submitted PRs as a native GitHub Stack automatically. This requires GitHub's github/gh-stack CLI extension — install it once:

gh extension install github/gh-stack
# or let stax install it for you:
st doctor --fix

That's it — no config needed. From then on, st ss/st bs auto-link multi-PR stacks under the hood, no extra command required. Existing stax PR body/comment stack links keep working; the native GitHub stack map is added on top. On gh-stack v0.0.8+, stax also prints the repository-scoped Stack number returned by GitHub.

st ss                    # auto-links native stack when available
st stack link            # manually re-link the current stack
st stack unlink 7        # unstack native Stack #7 remotely

Repos without the feature, users without the extension, and non-GitHub remotes keep the existing stax behavior — this is purely additive and never blocks a submit. To turn off gh-stack registration entirely, set native_stack = "off" under [submit] in ~/.config/stax/config.toml, or pass st submit --no-native-stack for a single run (see config reference). gh-stack v0.0.8+ uses GitHub's public Stacks REST API and supports the normal GitHub CLI authentication sources, including GH_TOKEN/GITHUB_TOKEN. For older link-capable versions, stax strips those overrides before gh stack operations so the extension can fall back to an OAuth-authenticated gh login. st doctor always shows the installed version, marks anything below v0.0.8 as out of date, and can upgrade it with st doctor --fix. Native Stack updates are append-only; to remove or insert PRs, run st stack unlink <stack-number> and then link again. Argument-free st stack unlink retains the active locally tracked behavior.

→ Native GitHub Stacks guide

Merge from the bottom of the stack up to your current branch, with CI and readiness checks:

st merge                  # local cascade merge
st merge --when-ready     # wait/poll until PRs are mergeable
st merge --ds             # merge ancestors, rebase current branch
st merge --stack          # GitHub/GitLab: preserve lower PR/MR merged state through one tip merge
st merge --stack --full   # stack-merge the full stack even from the middle
st merge --remote         # merge remotely on GitHub while you keep working
st merge --all            # merge the whole stack regardless of position

GitLab stack merge checks project merge settings first, sends squash: false, and accepts only the default preserving method; explicit stack rebase or squash is rejected. GitHub also rejects those rewriting methods for multi-PR stack ranges before mutation because lower PRs could not reach merged state; a single selected GitHub PR may still use them. Gitea/Forgejo stack merge is not supported.

→ Merge and cascade

When a rebase stops on a conflict, st resolve sends only the conflicted text files to your configured AI agent, applies the result, and resumes the rebase automatically. If the AI returns invalid output, touches a non-conflicted file, or leaves extra conflicts behind, stax bails out and preserves the in-progress rebase so you can inspect or continue manually.

st resolve
st resolve --agent codex --model gpt-5.3-codex

Before each rebase, stax also runs a preflight repair that compares the stored parent boundary against merge-base(parent, branch). When they diverge sharply — the “my restack hit conflicts on files I never touched” case — stax automatically uses the merge-base boundary for that rebase and prints a one-line notice. Silence the notice with [restack] preflight_warn = false or --quiet; disable the automatic correction with [restack] preflight_auto_repair = false.

restack, submit, sync, and reorder each snapshot branch state before they touch anything. Recovery is one command away.

st restack
st undo
st redo

→ Undo/redo safety

Bare st launches a full-screen TUI for browsing stacks, inspecting branch summaries and cached patches, watching live CI hydrate, and running common ops without leaving the terminal. Stack/Summary/Patch pane visibility is remembered per repo.

→ TUI guide

The native GUI opens a repository-scoped workspace with searchable Stack, Changes, and Inspector panes. It can check out, create, rename, delete, move, and reorder local branches; restack the selected branch or all tracked branches; submit the current stack as Draft; open the selected PR; and safely undo or redo fully local recorded operations. Destructive and history-rewriting actions show exact previews and confirmations, including explicit auto-stash follow-ups for dirty move/reorder/restack flows.

When the app starts without an explicit path, it reopens the most recently used project. Use the project dropdown in the toolbar to switch between recent projects or choose Add Project… to open another repository. An explicit st gui <path> launch still opens that repository.

Use / to search, 1/2/3 to toggle panes, and drag dividers to resize them; visibility and widths persist per canonical repository. The app also restores its last window size and reduces it to fit the current display after a monitor change. Native menus and keyboard shortcuts dispatch the same typed actions as the buttons. Submit is always confirmed first, pushes the current stack as Draft, and does not show CLI prompts or auto-open PR pages. st gui [path] only launches the app.

→ GUI guide

st create --ai -a --yes   # generate branch name + first commit message
st ss --ai --yes          # generate PR titles/bodies during submit
st gen                    # interactive: PR body, PR title, or commit message (AI)
st generate --pr-body     # non-interactive: refresh PR body from branch diff + context
st generate --pr-title    # non-interactive: refresh PR title from branch diff
st generate --commit-msg  # non-interactive: amend HEAD commit message with AI
st standup --ai           # spoken-style daily engineering summary
st standup --ai --style slack  # Slack-ready Yesterday/Today bullets

Each AI feature (generate, standup, resolve, lane) can use a different agent/model. st create --ai, st submit --ai, and st generate / st gen (PR body/title, commit message) share the generate setting. Configure with:

st config --set-ai

→ PR templates & AI · Reporting

Full reference: docs/commands/core.md · docs/commands/reference.md

Benchmarked with hyperfine on this repo. Absolute times vary by repo and machine; the ratios do not.

Run make benchmark-status for deterministic cold 10/50/100-branch scaling fixtures, or add global --trace to a command to see instrumented Git subprocess and wall-clock timings.

stax is wire-compatible with Freephite/Graphite for common stacked-branch workflows.

→ Full benchmarks · Compatibility notes

st config                  # open the config editor
st config --set-ai         # pick AI agent + model
st config --reset-ai       # clear saved AI pairing and re-prompt
st --default-config       # print annotated config template (options + allowed values)
st --skill                 # print bundled AI agent skill (SKILL.md format)

Config lives at ~/.config/stax/config.toml. When STAX_CONFIG_DIR is unset, a repo-root stax.toml overlays only the values it sets:

[submit]
stack_links = "body"   # "comment" | "body" | "both" | "off"
single_stack = "on"    # "on" | "off" — when "off", skip stack-link sync while only one PR exists

→ Full config reference

stax.tmux is a TPM-compatible plugin that puts your stack in the tmux status bar and adds keybindings for common actions:

• Live status bar — branch, stack position, PR state, CI state; auto-refreshes in the background
• Keybindings — prefix + S popup, prefix + ]/[ up/down, prefix + M-s sync
• Window auto-rename — tmux window title follows the current branch

Install via TPM:

set -g @plugin 'cesarferreira/stax.tmux'

See the stax.tmux README for full setup and configuration options.

AI and editor integration guides:

• Claude Code
• Codex
• Gemini CLI
• OpenCode
• pi
• PR templates + AI generation

Shared skill/instruction file used across agents: skills.md. Print the version bundled with your install: st --skill.

st changelog can generate notes between refs, and st changelog find [query] or st changelog --find [query] fuzzy-finds commits in the selected range. Use --path to scope either mode to a subdirectory.

Before opening a PR, run:

make test

On macOS this uses Docker when available. make test-native is the guarded fallback: it checks the file-descriptor limit, sanitizes the environment, and runs nextest with the optimized test profile. Native macOS timings can still vary substantially with endpoint-security tooling, so Docker remains the recommended full-suite path.

To cut a release, run:

make release                  # default minor bump
make release LEVEL=patch      # patch bump
make release LEVEL=major      # major bump

Release automation regenerates CHANGELOG.md with git-cliff inside cargo release's pre-release hook, grouping the commits since the latest v* tag under the new version (config in cliff.toml). See docs/workflows/releasing.md.

Project docs and architecture: docs/index.md. Contributor guidelines: AGENTS.md.

MIT © Cesar Ferreira