GitHub Stacked PRs CLI
The GitHub CLI extension gh stack and an agent skill: a chain of dependent branches and PRs with rebase, submit and merge of the whole stack
- 1,712 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The commands push branches to GitHub, open PRs and merge them together with every unmerged one below
- A rebase rewrites the history of local branches, and `sync --prune` deletes local branches of merged PRs
- `gh stack unstack` removes the stack on GitHub, and all work goes through your GitHub CLI authorization
Install
- Works in
Manual install
gh extension install github/gh-stackNeeds GitHub CLI 2.0 or newer and Git 2.36 or newer. Update with `gh extension upgrade stack`.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The commands push branches to GitHub, open PRs and merge them together with every unmerged one below
- A rebase rewrites the history of local branches, and `sync --prune` deletes local branches of merged PRs
- `gh stack unstack` removes the stack on GitHub, and all work goes through your GitHub CLI authorization
This is third-party code. Review the repository files before installing.
What it does
GitHub Stacked PRs is the official GitHub CLI extension for stacks: an ordered chain of branches where each branch builds on the previous one and gets its own pull request. Each PR's base is set to the branch below it, so a reviewer sees only the diff of that layer. The bottom branch rests on the trunk and merges first. The `gh stack init` command creates a stack, `gh stack add` adds a branch on top, `gh stack push` pushes all branches and `gh stack submit` opens PRs and links them into a stack on GitHub. The `up`, `down`, `top` and `bottom` commands walk the layers. `rebase` rebases branches onto each other, `sync` fetches, reconciles the stack with GitHub, rebases and pushes, `merge` merges a PR and every unmerged one below it, and `unstack` takes a stack apart. Metadata lives locally in a `gh-stack` file inside the git directory, and layers can sit in different worktrees. The gh-stack skill teaches an agent to use these commands without interactive screens: instead of bare commands it calls `gh stack view --json`, `gh stack submit --auto` and `gh stack merge <target> --yes`, and on exit code 3 it walks through rebase conflict resolution. Separate reference files explain how to split work into layers and cover failures.
Who it is for. For developers on GitHub who cut large changes into a chain of small PRs, and for agents assigned such work in a repository.
Good fit when
- A task in three parts (auth, API, interface) must be split into dependent PRs that can be reviewed separately
- The bottom PR was changed after review and all branches above it need rebasing with one command
- A whole stack or part of it must be merged with one command, not by hand in the right order
- An agent must run a stack from the console without hanging on prompts and full-screen screens
- You need the stack state as JSON: which branch is merged and where a rebase is needed
Not a fit when
- The repository is hosted outside GitHub: the extension works through the GitHub API
- You need several parallel branches off one branch: a stack is strictly linear, with one parent and at most one child per branch
- Git is older than 2.36 or GitHub CLI is not installed and authenticated
- You need to change the stack makeup without an interactive terminal: `modify` works only in a full-screen screen, and for scripts `unstack` and a fresh `init` remain
- You need a wrapper over `gh` with compact output for agents: the catalog has gh-axi
Example request
Split this task into three layers: the database migration, the API and the interface. Create the stack, submit it to GitHub as drafts and show the state as JSONLimitations
GitHub CLI 2.0 or newer and Git 2.36 or newer are required. If the repository has several remotes, set `remote.pushDefault` or pass `--remote` before `push`, `submit`, `sync` and `rebase`.
Without the `--json`, `--auto` and `--yes` flags some commands open prompts or a full-screen screen and hang in an agent shell. The `gh stack modify` screen starts only by hand.
A stack can hold up to 100 PRs. If stacks are not enabled on the repository, the commands return code 9. The steps to take after a squash merge are described in the troubleshooting reference.
PR titles and descriptions are generated automatically and edited later with `gh pr edit`. The extension checks for a new version and writes about it to stderr once a day; the `GH_STACK_NO_UPDATE_NOTIFIER=1` variable turns this off.
Stack metadata lives in `.git/gh-stack`: do not mix old and new versions of the extension in one clone.
How to disable. Run `gh extension remove stack` and delete the gh-stack skill folder from the agent's skills directory. The `gh-stack` file in the git directory can be deleted by hand; it is not part of the repository. Stacks on GitHub are removed with `gh stack unstack`.
FAQ
How does a stack differ from an ordinary PR?
Each PR in a stack is still an ordinary pull request, and its base is the branch of the PR below it; the main branch plays no such role. GitHub knows about the link between them, and a reviewer sees only the diff of their layer.
How many PRs can a stack hold?
Up to 100. If the work needs more, it is split into several stacks.
Where does the extension keep stack data?
Locally in a `gh-stack` file inside git's common directory, by default `.git/gh-stack`. The file is not committed, and all linked worktrees of the clone share it.
How do I merge a stack?
With `gh stack merge` and a PR or stack number. A PR number merges it and every unmerged one below it, a stack number merges the whole stack. The operation either completes entirely or does nothing. If the base branch has a merge queue, the stack joins the queue and the queue picks the merge method.
Why does the skill forbid a bare `gh stack view`?
Commands check whether output goes to a terminal. In an agent's pseudo-terminal `view` opens a full-screen screen and blocks, so the skill requires `gh stack view --json`, and `gh stack submit --auto` for submitting.
What do I do about a conflict after a rebase?
It exits with code 3. After `gh stack rebase`, resolve the conflict, run `git add` and `gh stack rebase --continue`, or roll back with `--abort`. After `sync` the stack is already restored: run `gh stack rebase` again to reproduce the conflict.
Discussion
No questions or reviews yet.
Related
CLI toolsGitHub CLI skills
GitHub CLI skills (gh, gh-skill)
Official GitHub CLI skills: how an agent should call gh correctly and how to manage skills with gh skill
A GitHub CLI extension and agent skill that uploads screenshots, PDFs, archives and logs to issues and pull requests and returns a ready link
Garry Tan's skill suite that turns Claude Code into a virtual team: product, architecture, design, review, QA and shipping
Goal Workflow
goal-workflow
19 skills for Claude Code: PRD, spec, GitHub Issues, batch implementation with review and pull request merging, plus refactoring and diagrams
A CLI that opens a local git diff in the browser like GitHub's Files changed tab; comments copy out as prompts for an agent
A Claude Code plugin: 39 commands for PRs, review, commits and specs, nine expert roles and hooks, in eight language versions
README in short
The project description opens with installation, updating and a detailed explanation of new-version notices. It continues with a section on agent integration, a five-command quick start, a stack diagram with bottom and top layers, local metadata storage and git worktree handling. Most of the length is a command reference with flag tables and examples. The repository has Astro documentation with screenshots of the GitHub interface, an API reference, contribution rules and Go tests.
README badge
Original SKILL.md
--- name: gh-stack description: > Manages stacked PRs and splits multi-part work into reviewable branches with gh-stack. Use for stack creation, viewing, edits, push, submit, sync, rebase, merge, or checkout; when asked to split or isolate work for review; whenever a user mentions a stack, branch layers, dependent PRs, or gh stack; or when a stack is checked out. metadata: author: github version: "0.2.0" --- # gh-stack `gh stack` is a [GitHub CLI](https://cli.github.com/) extension for stacked branches and pull requests. A stack is an ordered chain of branches rooted on a trunk, where each branch has one PR based on the branch below it, so a reviewer sees only that layer's diff. `gh stack` prints a stack trunk-first, left to right: ``` (main) <- auth <- api <- frontend ``` Left is the **bottom**, right is the **top**. `auth` is based on `main` and merges first; `frontend` merges last. `up` moves toward the top, away from trunk; `down` moves toward it. Foundational work belongs at the bottom, code that depends on it above. For how to choose the layers, read `references/stack-design.md`. ## Setup Requires Git 2.36+ and an authenticated GitHub CLI. ```bash gh extension install github/gh-stack git config rerere.enabled true # remember conflict resolutions git config remote.pushDefault origin # required if the repo has more than one remote ``` ## Non-interactive use `gh stack` branches on whether **stdout is a TTY**. Piped, most commands error cleanly or print static text; under a PTY the same commands open a prompt or a full-screen TUI and block forever. Agent harnesses differ, so always pass the flags below instead of relying on that detection.