pi-graphite

Opinionated pi tools + skill that wrap the Graphite gt CLI for stacked PR workflows. Seven tools, one correct path.

graphite_status → (graphite_setup if needed) → graphite_sync → graphite_navigate
       → graphite_change → graphite_submit (dry-run) → graphite_submit (apply)

The extension wraps gt only. It deliberately does not call gh, edit PR titles/bodies, fetch review comments, or perform stack surgery (split / fold / move / squash / reorder). For those flows, run the underlying gt or gh command yourself in your own terminal; the agent should not invoke them from bash, as their defaults open interactive prompts, hunk pickers, or editors that will hang non-interactive sessions.

Requirements

• gt CLI installed and authenticated (gt auth).
• A pi runtime that loads npm or local pi packages.

Install

# global
pi install npm:pi-graphite

# project-local
pi install -l npm:pi-graphite

# from a local checkout
pi install /path/to/pi-graphite
# or, for one session
pi -e /path/to/pi-graphite

The package also ships a graphite skill (skills/graphite/SKILL.md) that pi auto-discovers. It describes the golden path and per-recipe tool calls; the agent loads it on demand.

Registered tools

Tool	Purpose	Wraps
graphite_status	Read-only snapshot: current stack + current branch + PR + restack hints	gt log --stack, gt info
graphite_setup	Initialize Graphite or track an existing Git branch with explicit parent	gt init --trunk, gt track --parent
graphite_sync	Start-of-day / after-merge cleanup + restack	gt sync
graphite_navigate	Move around the stack	gt checkout, gt up/down/top/bottom
graphite_change	Create / amend a stacked branch	gt create -am, gt modify -am, gt modify --into, gt absorb
graphite_submit	Push the entire stack and open/update PRs (dry-run by default)	gt submit --stack --no-edit --no-ai
graphite_recover	Continue / abort / undo	gt continue, gt abort, gt undo

Golden path

graphite_status
graphite_setup                               # only if repo not initialized or branch untracked
graphite_sync                                # at session start, or after merges
graphite_navigate action=checkout branch=…   # move to the target PR / parent
# user edits files
graphite_change action=create message="…"     # or action=amend
graphite_submit apply=false             # review the dry-run plan
graphite_submit apply=true confirmRemote=true

Conflict path:

# resolve files, then: git add -- <paths>
graphite_recover action=continue

Never run git rebase --continue after a gt command — use graphite_recover action=continue so Graphite propagates the resolution to dependent branches.

Conventions and guardrails

• Every tool requires absolute cwd.
• gt is invoked with --cwd <cwd> --no-interactive, no shell strings. Tools that support AI metadata pass --no-ai.
• Editor / pager / browser env is forced safe (GT_EDITOR=true, GT_PAGER=, BROWSER=true, …). Commands have a hard timeout.
• Interactive editor / hunk / browser / reorder paths are not exposed.
• Commands echoed in tool output are safe to copy-paste back into a shell.
• graphite_setup action=track_branch requires explicit branch, explicit parent, and confirmParent:true; do not guess parent if unclear.
• graphite_setup action=init_repo reset:true needs confirmDestructive:true.
• graphite_submit defaults to --dry-run; apply:true also needs confirmRemote:true. --force push also requires confirmRemote:true.
• graphite_sync with force or deleteAll needs confirmDestructive:true.
• graphite_recover action=continue refuses to proceed if tracked files still contain <<<<<<< markers, unless allowConflictMarkers:true.
• Output is ANSI-stripped, branded ("Graphite" not "Charcoal"), and truncated to ~50 KB / 2000 lines.
• Stderr is parsed into structured hints (notInitialized, conflictHalted, restackNeeded, trunkOutOfSync, branchNotTracked, noChangesStaged, checkedOutElsewhere, operatingOnTrunk, …).

Git hooks

Git hooks in the target repository run as normal; this extension does not bypass them. Treat them as part of your repo's trust boundary.

License

MIT