Stax Workflow
Use stax (stax) for stacked diffs and PR management.
Sandbox
ALL stax commands MUST be run with dangerouslyDisableSandbox: true. The stax CLI writes to .git/ and makes
network requests to GitHub — the sandbox blocks both.
Non-interactive mode
Stax commands that prompt for confirmation fail with "not a terminal" in Claude Code. Always pass the appropriate flag to skip prompts:
stax ss --no-promptfor submitstax rs -ffor syncstax merge -yfor mergestax restack -yfor restack (when conflicts are predicted)
Critical Rules
- NEVER create or update PRs unless the user explicitly asks in that message. Each PR operation requires fresh explicit consent.
- ALWAYS provide an explicit branch name to
stax create(e.g.stax create auth-refactor). - ALWAYS stack new branches on the current branch — never switch to trunk first. Even if the changes are logically independent, the default is to build a stack. Only branch off trunk when the user explicitly asks for it.
- Do not run
staxwith--helpor exploratory commands unless a command fails with an unexpected error. - Use
stax ss --no-prompt(orstax cascade) to push, notgit push. Raw pushes bypass stax's tracking. Only fall back togit pushwhen recovering from broken stax state.
Starting a session
Determine whether you are in the main working tree or an external worktree:
git rev-parse --git-dir --git-common-dirIf both lines are the same (e.g. .git / .git), you are in the main working tree. If they differ, you are in a
worktree.
Main working tree
Run stax rs -f to sync with remote. This cleans up branches whose PRs were merged outside stax (e.g., via the GitHub
UI) and prevents stale local state from causing submission failures.
External worktree
Do not run stax rs -f — syncing from an external worktree can be disruptive because it may affect the main working
tree's checkout state.
Instead, bootstrap stax:
- Check whether HEAD is detached:
git symbolic-ref HEADIf this fails, HEAD is detached. Create a branch:
git checkout -b <branch-name>- Register the branch with stax:
stax branch track --parent mainThen proceed with normal stax operations.
Core Operations
Create a stacked branch
stax create <branch-name>
git add <files>
git commit -m "commit message"Creates a new branch stacked on the current one. stax create only creates the branch — it does not stage or commit
anything. Always stage and commit separately after creating the branch.
Do not use stax create -m — it has been unreliable in practice (silently producing empty branches).
Submit / make PRs
All changes must be committed before submitting. stax ss only pushes and creates/updates PRs — it does not commit.
stax ss --no-promptSubmits the full stack — creates PRs for branches that don't have one, updates PRs for branches that do. Each branch becomes its own PR, linked in a stack.
--no-prompt creates new PRs as drafts. After submitting, for each newly created PR:
- Replace the stax-generated body — stax auto-populates PRs with an opinionated format. Overwrite it with your own description. Explain why the change was made, not what changed. If the commit body already contains a good description, use that. Do not use any content from the stax-generated body as a starting point.
gh pr edit <number> --body "<PR description>"- Mark the PR as ready:
gh pr ready <number>Use stax cascade as an alternative that also restacks before submitting.
Update the current branch
For small amendments to the current commit:
stax modifyStages all changes and amends them into the current commit. Optionally pass -m "new message" to change the commit
message.
For new commits, use git add + git commit as normal, then stax ss --no-prompt to push and update the PR.
Sync
stax rs -fPulls trunk, deletes merged branches. Does not rebase. Use this to clean up after merges.
To also restack (rebase) branches after syncing:
stax rs -f --restackRestack
stax restackRebases the current branch onto its parent. To restack all branches in the stack:
stax restack --allUse this after a branch in the stack was force-pushed or rebased on GitHub.
Merge a branch
stax merge -yMerges PRs from the bottom of the stack up to (and including) the current branch. Default merge method is squash.
To poll until ready (CI + approval) and then merge:
stax merge --when-ready -yMerge the entire stack
stax merge --all -yMerges every PR in the stack, bottom to top.
After Submitting
After every successful stax ss or stax cascade, you MUST display the GitHub PR URLs from the output to the user.
This applies to both PR creation and PR updates — always show the links.
Stack Visualization
stax ls— show the stack with PR and rebase status.stax ll— show the stack with PR URLs and details.
Commit Message Style
The first line of the commit message becomes the PR title. Keep it terse:
- "Add retry logic for flaky webhook delivery"
- "Fix: pagination cursor off-by-one"
For the body, explain why the change was made when the reasoning is non-obvious. Err on the side of brevity.
Recovery
stax undo— undo the last stax operation.stax redo— reapply an undone operation.
Installing Permissions
When the user says /stax install permissions, configure the agent's user-global (not project-specific) settings to
always allow the following shell commands without prompting:
staxwith any argumentsgh prwith any arguments
Both must be allowed to run outside the sandbox (they write to .git/ and make network requests to GitHub).