# Gh Stackx

> Use the gh-stackx gh extension to submit, sync, and merge stacked pull requests when the GitHub Stacked PRs API is unavailable.

- Skill: `theplenkov/gh-stackx` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add theplenkov/gh-stackx`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theplenkov/gh-stackx/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: theplenkov (https://skillmd.com/u/theplenkov)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/theplenkov/gh-stackx

---


# gh-stackx

Use the `gh-stackx` `gh` extension to manage **stacked pull requests** on repositories that do not have the private-preview GitHub Stacked PRs API.

## When to use

- You want to open a series of dependent PRs.
- `gh stack submit` fails with `⚠ Stacked PRs are not enabled for this repository`.
- You need to keep PR bases correct as the stack is rebased or merged.
- You want to merge a stack from the top down without manually editing PR bases.

## Security notice

`gh-stackx` is a convenience wrapper around the `github/gh-stack` `gh` CLI extension. It runs locally with the user's configured `gh` authentication. This skill does not collect, store, or forward GitHub credentials, and it does not install extensions or other skills automatically. Always review the source of any `gh` extension before installing it.

## Prerequisites

- `gh` CLI installed and authenticated.
- `github/gh-stack` extension installed for local stack operations.
- `gh-stackx` extension installed.

Do not run `gh extension install` automatically. Installation must be explicit, and the source repositories (`github/gh-stack` and `ThePlenkov/gh-stackx`) should be reviewed before granting `gh` credentials. See the repository README for installation steps.

## Core concepts

- **Trunk** — the base branch, usually `main`.
- **Stack** — an ordered list of branches where each branch builds on the previous one.
- **Bottom** — the branch closest to trunk.
- **Top** — the branch farthest from trunk.
- **Base** — the parent branch for a PR. The bottom layer uses trunk; every other layer uses the previous branch.

## Workflow

### Create a stack

```bash
git checkout main
git pull origin main

gh stackx init feature/auth
# work and commit

gh stackx add feature/api
# work and commit

gh stackx add feature/ui
# work and commit
```

### Submit PRs

```bash
gh stackx submit       # drafts
gh stackx submit --open
```

`submit` pushes all branches and creates/updates PRs bottom-up with the correct `--base` and `--head`. Each PR body includes a `## Stack` GFM table showing the full stack from top to trunk.

### Sync after trunk or parent PR changes

```bash
gh stackx sync
gh stackx sync --remote upstream
```

`sync` runs `gh stack sync` and then updates every open PR base with `gh pr edit --base`.

### Merge top-down

```bash
gh stackx merge
gh stackx merge --squash
gh stackx merge --rebase
```

`merge` starts at the top of the stack and merges each open PR with `gh pr merge`.

## Local navigation

These pass through to `github/gh-stack`:

```bash
gh stackx view --json
gh stackx up
gh stackx down
gh stackx top
gh stackx bottom
gh stackx trunk
```

`gh-stackx` reports its own repo and version from `manifest.yml`:

```bash
gh stackx --version
gh stackx version
gh stackx -v
```

## Important rules

- Keep the working tree clean before `sync` or `merge`; rebase operations fail on uncommitted changes.
- Create PRs bottom-up so each base exists before the child PR is opened.
- Merge top-down so dependent PRs are merged before their parents move.
- Do not commit `.git/gh-stack`. It is local metadata.

## Troubleshooting

- `gh stackx view` fails: ensure `github/gh-stack` is installed.
- A PR has the wrong base: run `gh stackx sync`.
- `submit` or `merge` stops with errors: fix the underlying `gh pr` issue, then re-run.

## Further reading

The full workflow is already inline above. For more, see the repository:

- [Usage guide](https://github.com/ThePlenkov/gh-stackx/blob/main/docs/usage.md) — practical walkthrough with examples.
- [Stacked PR methodology](https://github.com/ThePlenkov/gh-stackx/blob/main/docs/methodology.md) — why and how stacked PRs work.
- [Specification](https://github.com/ThePlenkov/gh-stackx/blob/main/skills/gh-stackx/docs/spec.md) — full command and architecture specification.
- [REVIEW.md](https://github.com/ThePlenkov/gh-stackx/blob/main/REVIEW.md) — review policy for this repository.
- [AGENTS.md](https://github.com/ThePlenkov/gh-stackx/blob/main/AGENTS.md) — how to work on this repository.