maol-stack

maol-stack is a clean-room Node.js CLI for stacked Git branches. Its implementation and metadata are fully local, and stack submission talks directly to Git and GitHub through the installed git and gh commands.

The scope covers creating and tracking branches, amending changes, moving and squashing branches, restacking descendants, recovering from conflicts, undoing mutations, navigation, and submitting stacks as GitHub pull requests.

Run with npx

From this project:

npm install
npm run build
npx --yes . --version

From npm:

npx maol-stack --version

maol-stack requires Node.js 22 or newer and an existing Git repository.

Local workflow

npx maol-stack init --trunk main

# Make the first change, then create its branch and commit it.
npx maol-stack create feature-base --all --message "feature: base"

# Make a dependent change and stack it on the current branch.
npx maol-stack create feature-ui --all --message "feature: ui"

# Amend a parent and automatically restack descendants.
npx maol-stack checkout feature-base
npx maol-stack modify --all

# Restack explicitly after changing a parent outside maol-stack.
npx maol-stack restack --upstack

# Push every branch and create or update its stacked GitHub PR.
npx maol-stack submit --stack

If an explicit restack conflicts, maol-stack leaves Git's rebase paused:

# Resolve files, then either continue or restore all saved branch tips.
npx maol-stack continue --all
npx maol-stack abort --force

modify, move, and squash attempt descendant restacks automatically. In non-interactive mode, an automatic conflict is aborted and reported as a warning; run an explicit restack --upstack to resolve it.

Commands

• init, track, untrack
• create, modify, move, squash
• restack, continue, abort, undo
• submit
• log, state
• checkout, up, down, top, bottom, parent, children, trunk
• add
• mcp

Use npx maol-stack <command> --help for options.

Submit a stack

submit --stack walks from the bottom of the current stack through all of its descendants. It pushes each branch before creating or updating a GitHub pull request whose base is the logical parent branch:

npx maol-stack submit --stack

New pull requests use the branch's latest commit subject as their title. Useful options include:

# Show the complete plan without changing the remote or GitHub.
npx maol-stack submit --stack --dry-run

# Create new pull requests as drafts.
npx maol-stack submit --stack --draft

# Submit through the current branch, without its descendants.
npx maol-stack submit

maol-stack records the last successfully pushed SHA. The default push uses an explicit --force-with-lease and refuses to overwrite a remote branch that changed since the previous submission. --force is available as an explicit override after reviewing the remote changes. An out-of-sync trunk does not block submit by default; --ignore-out-of-sync-trunk emits an explicit warning. The apply path uses the authenticated GitHub CLI (gh) directly.

Restack safety and parity

maol-stack stores the logical parent and previous parent revision for every tracked branch in Git's common directory. A restack rebases each branch with the equivalent of:

git rebase --onto <current-parent> <recorded-parent-revision> <branch>

Before a mutation it records branch refs, metadata, the active branch, and a binary worktree patch. This supports abort and undo, including restoring a change consumed by modify as an unstaged local modification.

The differential suite currently has 173 passing comparisons against a reference stacked-branch CLI, with 10 skipped. See PARITY.md for what is skipped and why. The comparisons cover:

• clean and no-op descendant restacks;
• content, add/add, and modify/delete conflicts;
• automatic conflict rollback and explicit conflict pause;
• continue, forced abort, undo, and consecutive conflicts upstack;
• multi-commit children and empty branches;
• staged and unstaged working trees;
• branches checked out in another worktree;
• move, move --only, and squash;
• initialization, reset, tracking, force tracking, and forced untracking;
• navigation, directed navigation, checkout messages, and relationship output;
• command aliases and quiet output;
• successful commit/amend output and common non-interactive errors;
• multiple sibling stacks, nested forks, and serialized state output;
• all supported command help, top-level help, yargs parser errors, and streams;
• interactive checkout search, arrows, wraparound, fallback, cancellation, forks, scrolling, colors, and raw terminal control sequences;
• submit --stack selection, dry-run, publication, metadata, review, transport, trunk, restack, and error options.

It compares exit status, functional stdout/stderr, active/detached state, rebase state, porcelain status, branch trees, commit counts, and the ancestry matrix. Stateful tip: blocks are removed from the comparison because their counters live in the reference CLI's global configuration. The suite needs the configured reference executable and its credentials, so it cannot run in CI:

npm run test:parity

Remote publication is covered independently by the internal GitHub test suite.

MCP server

Start the stdio MCP server with:

npx maol-stack mcp

It exposes:

• run_maol_stack_cmd, which runs a CLI command in a selected repository;
• learn_maol_stack, which returns the safe stacked-branch workflow.

Install in Claude Code

Copy and paste this command in a terminal to make the MCP server available in Claude Code from every repository:

claude mcp add --scope user maol-stack -- npx --yes maol-stack mcp

Confirm the installation with:

claude mcp get maol-stack

Install in Codex

Copy and paste this command in a terminal to make the MCP server available in Codex:

codex mcp add maol-stack -- npx --yes maol-stack mcp

Confirm the installation with:

codex mcp get maol-stack

Development

npm run check
npm run test:coverage
npm run test:parity
npm pack --dry-run

The implementation is MIT licensed.