Maiao

Note: This is a community fork of adevinta/maiao. The original maintainers are no longer at Adevinta and the upstream repository is no longer actively maintained. This fork continues development under runetes/maiao.

Gerrit-style code review workflow for GitHub, GitLab, Gitea, Forgejo, Bitbucket Cloud, and Cursor Origin

Maiao brings the power of stacked pull requests (or merge requests) to your git hosting provider, enabling you to break large features into small, reviewable commits where each commit becomes its own PR/MR.

What is Maiao?

Maiao provides the git review command that:

• Creates one PR/MR per commit in your branch
• Stacks PRs/MRs automatically with proper parent-child dependencies
• Registers native stacks when available (GitHub Stacks, GitLab auto-detected stacks)
• Manages fixups elegantly using git commit --fixup
• Tracks commits via Change-IDs (using the Gerrit commit-msg hook)
• Auto-rebases your stack when PRs/MRs get merged
• Auto-detects your provider from the remote URL

Supported Providers

Provider	PR/MR type	WIP/Draft	Native stacks
GitHub	Pull Request	API field	Yes (explicit registration)
GitLab	Merge Request	Draft: title prefix	Yes (auto-detected from target branch, up to 20 MRs)
Gitea	Pull Request	WIP: title prefix	No
Forgejo/Codeberg	Pull Request	WIP: title prefix	No
Bitbucket Cloud	Pull Request	Not supported	No
Cursor Origin (beta)	Pull Request	API field	Yes (parentPullNumber)

Maiao auto-detects the provider from your remote URL for known hosts (github.com, gitlab.com, codeberg.org, bitbucket.org, origin.cursor.com). For self-hosted instances, it prompts on first use and saves the choice to git config maiao.provider.

Quick Example

# Make multiple commits
git commit -m "Add user authentication"
git commit -m "Add authorization middleware"
git commit -m "Add admin endpoints"

# Create stacked PRs/MRs for all commits
git review

Result: Three PRs/MRs created and stacked:

• PR #1: Add user authentication → main
• PR #2: Add authorization middleware → PR #1
• PR #3: Add admin endpoints → PR #2

Key Benefits

• Granular Reviews: Each commit reviewed independently for faster, focused feedback
• Clear History: One logical change per PR/MR maintains clean git history
• Easy Fixups: Address review feedback with git commit --fixup <sha>
• Automatic Stacking: Tool manages PR/MR dependencies automatically
• Native Stacks: Integrates with GitHub Stacks and GitLab's auto-detected stacks
• Merge Detection: Stack updates automatically when PRs/MRs merge
• Rebase Integration: Handles upstream changes gracefully
• Multi-Provider: Works across GitHub, GitLab, Gitea, Forgejo, Bitbucket Cloud, and Cursor Origin

Native GitHub Stacks

Maiao treats GitHub native stacks as a progressive enhancement. When two or more PRs are pushed, Maiao probes the Stacks API (cached for 24 hours) and registers the PRs as a stack if supported. On older GitHub Enterprise instances the feature is silently skipped — branch-based stacking still works as before.

# Control via git config (default: auto)
git config maiao.useNativeStack auto   # use when available, skip otherwise
git config maiao.useNativeStack true   # always register; warn if unavailable
git config maiao.useNativeStack false  # disable entirely

Coding agents

Maiao ships a skill teaching an agent the workflow: how to shape commits so each one is worth a pull request, and how to create, update, reorder and withdraw the changes in a stack. The same skill is read by Claude Code, Cursor, Codex, Copilot, Gemini, OpenCode and the other harnesses that follow the Agent Skills layout.

Claude Code can install it as a plugin:

/plugin marketplace add runetes/maiao
/plugin install maiao@maiao

Or install the copy embedded in the binary, which is guaranteed to describe the maiao you are actually running and stamps the version it came from into SKILL.md. With no harness named, that copy is written for every harness detected on this machine. Nothing detected yet falls back to ~/.agents/skills, the directory Cursor, Codex, Copilot and OpenCode share:

git review install --skill                    # every harness found under $HOME
git review install --skill --harness cursor   # only Cursor (~/.cursor/skills)
git review install --skill --harness cursor . # this project (.agents/skills)
git review install --skill .claude            # an explicit directory

In a repository, Cursor, Codex, Gemini, Copilot and OpenCode all read .agents/skills, so naming more than one of them installs the skill once. Claude Code reads .claude/skills instead. A harness that is not in the list still works: pass the directory it reads. git review install --help names the harnesses.

Or, to pull it into a marketplace manifest you already keep, as a git-subdir source:

{
  "name": "maiao",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/runetes/maiao.git",
    "path": "skills/maiao"
  }
}

From the Claude plugin the skill is invoked as /maiao:git-review; every other harness invokes it as git-review. Pair it with git review install --global, a token in the environment, and — on a self-hosted host — git config --global maiao.provider, so no run of git review ever stops to ask a question the agent cannot answer. See Non-interactive use.

Documentation

• Getting Started - Installation and workflow guide
• How Does It Work - Technical details and architecture
• Pricing - Free and open source

Learn About Stacked Diffs

Maiao implements the stacked diffs methodology. Learn more:

• Stacked Diffs Versus Pull Requests - Jackson Gabbard's foundational article on the philosophy
• Graphite's Guide to Stacked Diffs - Comprehensive guide to the workflow and best practices
• The Pragmatic Engineer: Stacked Diffs - Industry analysis and adoption patterns (paywalled)

Why "Maiao"?

As Maiao encourages users to create smaller and nicer commits in their pull requests, it has been given the name of a tiny island:

Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

License

MIT License - see DISCLAIMER.md for details.