graphite

Stacked pull-request workflow with the Graphite CLI (gt). Teaches Claude to drive gt for creating, syncing, restacking, and submitting branch stacks.

Overview

Graphite is a developer-tool layer on top of git and GitHub that makes stacks of small PRs ergonomic. A stack is a sequence of branches where each builds on its parent and lands as its own PR. This plugin makes Claude aware of the stack model so it uses gt instead of raw git for branch creation, rebasing, and pushes.

The plugin includes:

• A skill (graphite) that activates whenever stacked-PR or gt work comes up. It documents the mental model, the golden path, conflict-resolution patterns, worktree handling, and multi-trunk setups.
• A setup skill (graphite-setup) that activates when configuring a repo for Graphite — GitHub branch protection, merge queue choice (Graphite / GitHub native / external), CI triggers, ignoring graphite-base/* branches, and stack-aware CI Optimizations.
• A merge-queue skill (graphite-merge-queue) that handles runtime operation of Graphite's queue — label-based enqueueing, stack cascade rules, dequeueing, and reading the configured label from .please/config.yml.
• 16 slash commands covering basic workflows (create, submit, sync, log, checkout, modify), advanced operations (restack, absorb, split, squash, fold, track, reorder, move, get), and merge-queue operation (merge-queue).

Prerequisites

Install and authenticate the Graphite CLI first — this plugin drives the CLI, it does not install it.

# macOS
brew install withgraphite/tap/graphite

# Other platforms / npm
npm install -g @withgraphite/graphite-cli

# Authenticate (one time)
gt auth

Then in your repo:

gt init   # select trunk branch (usually main)

Installation

claude
/plugin marketplace add pleaseai/claude-code-plugins
/plugin install graphite@pleaseai

Commands

Basic

Advanced

Merge queue configuration

Graphite supports four merge-queue postures. Declare which one your repo uses so the plugin picks the right merge path:

graphite:
  enabled: true
  merge-queue:
    mode: graphite          # graphite | github-native | external | none
    label: "merge-queue"     # used only when mode: graphite (must match Graphite settings)

Fallback chain for the label (when mode: graphite): graphite.merge-queue.label → $MERGE_QUEUE_LABEL → merge-queue.

How it works

The skill loads automatically when the user mentions Graphite, gt, stacked PRs, or works in a repo containing .git/.graphite_repo_config. It teaches Claude to:

• Prefer gt over raw git for branch operations on tracked branches
• Run gt ls before any destructive operation to confirm stack shape
• Resolve restack conflicts via gt add . → gt continue -a (not git rebase --continue)
• Handle worktrees: run stack commands from each owning worktree
• Avoid git rebase on tracked branches (corrupts Graphite metadata)

A SessionStart hook also detects .graphite_repo_config inside the git common dir (worktree-safe via git rev-parse --git-common-dir) and injects a short notice so Claude reaches for gt from the first turn — even before any keyword in the conversation triggers the skill. If the gt CLI is missing, the hook surfaces the install command instead.

Links

• Graphite docs
• CLI quick start
• Command cheatsheet
• Command reference

Setup & configuration (covered by the graphite-setup skill)

• GitHub configuration guidelines
• Setup: merge queue integration
• Setup: recommended CI settings
• Stacking and CI

Merge queue (covered by the graphite-merge-queue skill)

• Get started with Merge Queue
• Set up the Merge Queue