---
name: stax
description: Use only when the user explicitly invokes `/stax` or `$stax`.
title: stax
canonical_url: https://skilld.dev/gh/scode/dotfiles/stax
last_updated: 2026-10-25T20:28:40.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install scode/dotfiles/stax`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/stax`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/scode/dotfiles/stax) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/stax`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/stax --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/stax --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Stax Workflow

Use [stax](https://cesarferreira.com/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-prompt` for submit
- `stax rs -f` for sync
- `stax merge -y` for merge
- `stax restack -y` for restack (when conflicts are predicted)

## Critical Rules

1. **NEVER create or update PRs unless the user explicitly asks in that message.** Each PR operation requires fresh
   explicit consent.
2. **ALWAYS provide an explicit branch name to `stax create`** (e.g. `stax create auth-refactor`).
3. **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.
4. **Do not run `stax` with `--help` or exploratory commands** unless a command fails with an unexpected error.
5. **Use `stax ss --no-prompt` (or `stax cascade`) to push**, not `git push`. Raw pushes bypass stax's tracking. Only
   fall back to `git push` when recovering from broken stax state.

## Starting a session

Determine whether you are in the main working tree or an external worktree:

```bash
git rev-parse --git-dir --git-common-dir
```

If 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:

1. **Check whether HEAD is detached:**

```bash
git symbolic-ref HEAD
```

If this fails, HEAD is detached. Create a branch:

```bash
git checkout -b <branch-name>
```

2. **Register the branch with stax:**

```bash
stax branch track --parent main
```

Then proceed with normal stax operations.

## Core Operations

### Create a stacked branch

```bash
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.

```bash
stax ss --no-prompt
```

Submits 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:

1. **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.

```bash
gh pr edit <number> --body "<PR description>"
```

2. **Mark the PR as ready:**

```bash
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:

```bash
stax modify
```

Stages 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

```bash
stax rs -f
```

Pulls trunk, deletes merged branches. Does not rebase. Use this to clean up after merges.

To also restack (rebase) branches after syncing:

```bash
stax rs -f --restack
```

### Restack

```bash
stax restack
```

Rebases the current branch onto its parent. To restack all branches in the stack:

```bash
stax restack --all
```

Use this after a branch in the stack was force-pushed or rebased on GitHub.

### Merge a branch

```bash
stax merge -y
```

Merges 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:

```bash
stax merge --when-ready -y
```

### Merge the entire stack

```bash
stax merge --all -y
```

Merges 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:

- `stax` with any arguments
- `gh pr` with any arguments

Both must be allowed to run outside the sandbox (they write to `.git/` and make network requests to GitHub).
