stax

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

Install  ·  Quickstart  ·  Commands  ·  Docs

Why stax

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.

Install

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

Quickstart

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 skills update fetches and compares the fully rendered skill file for each selected harness, so it refreshes changed instructions even when the installed package-version marker matches; byte-identical files are left untouched. st skills list reports only those local package-version markers, not whether the remote instructions have changed.

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

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

Next: Quick Start guide · Merge & cascade workflow

Highlights

Parallel AI lanes

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

Native GitHub Stacked PRs

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.1.0 as out of date (v0.1.0 adds gh stack merge, see below), 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

Cascade stack merge

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
st merge --ignore-failed-ci  # merge despite a red CI rollup (e.g. only optional checks failed)

On GitHub, if the current stack is a confirmed-enabled native GitHub Stack and gh-stack v0.1.0+ is installed, st merge --stack delegates to gh stack merge instead — GitHub lands every selected PR up to the tip atomically, or none of them. Older gh-stack versions fall back to the flow below with a note: pointing at gh extension upgrade stack.

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

AI conflict resolution

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.6-terra

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.

Undo / redo

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

Interactive TUI

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

Localhost web workspace

st web starts a secure, browser-based workspace on 127.0.0.1 — the same three-pane layout as the TUI, available everywhere (Linux, macOS, SSH sessions):

st web            # opens port 8787, or warns and uses a free port if busy
st web --port 0   # ephemeral port
st web --no-open  # start without opening browser; prints URL

Run st web from anywhere inside a Git worktree, or pass any path inside one; stax discovers and opens the worktree root automatically.

Binds 127.0.0.1 only with an unguessable session token in the URL, CSRF protection on every mutating POST, and one-mutation-at-a-time enforcement. Requests without an Origin remain supported; when present, Origin must exactly match http://127.0.0.1:<actual-bound-port>. No --host flag — it cannot be exposed to the network.

→ Web workspace guide

AI branch names, PR details, and standups

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
st standup --ci           # include CI failures for selected stack branches
st standup --ci --json    # activity + explicit signal availability metadata

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

Projects can also define PR-specific writing rules in a repo-root stax.toml (or globally in ~/.config/stax/config.toml):

[ai.generate]
title = "Prefix titles with the issue key"
body = "Include testing and rollout sections"

These rules apply to AI-generated PR titles and bodies from generate and submit --ai; commit-message generation is unchanged.

→ PR templates & AI · Reporting

Commands

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

Performance

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

Configuration

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

[ai.generate]
title = "Prefix titles with the issue key"
body = "Include testing and rollout sections"

→ Full config reference

Integrations

tmux

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.

Contributing

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.

License

MIT © Cesar Ferreira