🐙 pi-prs

A Pi extension that owns GitHub pull request state for your session: footer widgets, review feedback, CI failures, and watching.

🚀 Installation

pi install npm:pi-prs

Install GitHub CLI and authenticate it before using the extension.

✨ Usage

pi-prs resolves the pull request for the current branch on its own and keeps it fresh in the background. Fork and upstream remotes both work, and switching branches re-resolves immediately.

Start watching that pull request for review feedback and CI failures:

/pr watch

The extension sends unresolved review feedback and current CI failures to pi, then checks GitHub every 30 seconds for new comments, reviews, and failed checks. New feedback starts an agent turn when pi is idle or steers its next turn when it's busy.

CI messages include the commit, failed check names, and links. GitHub Actions failures also include short diagnostic excerpts as soon as the failed job finishes, even while the rest of the run continues; expand the message to see them. Other CI providers and unavailable logs fall back to check names and links. Diagnostics cover at most three jobs per batch, with up to 80 lines or 4,000 characters per excerpt.

Each failed execution is delivered once while you stay on the same pull request in the session, including across /pr unwatch and /pr watch. Failed reruns and failures on new commits are delivered again. Only the latest execution of each named check within a workflow contributes to CI status and feedback. Successful reruns clear superseded failures from the footer. Canceled checks and checks awaiting approval show as failed in the footer but don't start agent turns; neither do skipped or passing checks. Large sets of failures arrive in batches of up to 20 checks, and failures from superseded commits are discarded. Checks with incomplete or unfamiliar statuses stay pending without hiding other failures. GitHub read errors retain the last known CI status and slow polling until reads succeed again, whether or not you're watching.

Stop watching:

/pr unwatch

This stops both review and CI feedback; footer updates continue. Watching also stops automatically when the pull request closes or merges.

Babysit review feedback

Start watching with a prompt that asks pi to assess and handle review feedback:

/pr watch --babysit

Once watching starts, --babysit adds a normal user message before the initial review feedback and CI failures are delivered. It starts an agent turn when idle or steers the agent when busy. Plain /pr watch delivers feedback without adding the prompt; the extension doesn't perform GitHub actions itself.

The prompt instructs the agent to:

• Critically verify each finding against the current code and intended behavior.
• Fix valid findings, run relevant checks, and commit and push according to the repository's workflow.
• Reply on GitHub with the addressing commit SHA or an evidence-based rejection reason, then resolve the review thread after the reply succeeds.
• Report blockers and leave unfinished threads unresolved. Comments without review threads receive replies but cannot be resolved.

These are instructions for the agent, not an enforced automation policy. They apply to feedback already in context and future feedback in this session until you tell the agent to stop. /pr unwatch stops new deliveries; it doesn't retract the prompt or cancel work already underway.

🧩 Footer widgets

When pi-fancy-footer is installed, pi-prs publishes the pull request number, unresolved review threads, failed CI checks, and a watching indicator. You can change their placement, visibility, and colors with /fancy-footer.

The pull request icon tells you whether the PR can merge:

Auto-merge doesn't change the color. Unmet requirements include missing approvals, unresolved conversations that branch protection requires you to resolve, and an outdated branch. All icons dim when GitHub state is degraded.

The other icons each have their own shape:

• The ✕ and its count show failed CI checks and link to the first failure. It appears only while checks fail, since the pull request icon already shows pending checks. It uses the footer's default icon color, because the red pull request icon already signals the failure.
• The comment icon and its count show unresolved review threads.
• The eye appears alone while /pr watch is active. Like the comment icon, it uses the footer's default icon color, which you can change in /fancy-footer.

🔌 Extension API

pi-prs is the only extension that should poll GitHub in a session. Other extensions consume its state from the event bus instead of shelling out to gh:

import { createPiPrClient } from "pi-prs/api";

export default function (pi) {
  const client = createPiPrClient(pi);
  client.onState((state) => {
    // state.pullRequest?.ci, .mergeState, .unresolvedThreadCount, .isDraft, …
  });
  client.onFeedback((event) => {
    // event.feedback: new review findings
  });
  client.onCiFailure((event) => {
    // event.headRefOid, event.failures: new failed CI executions
  });
}

Publishing a pi-prs:feedback or pi-prs:ci-failure event yourself sends that feedback to pi as a steering message.

🧰 Requirements

• GitHub CLI, authenticated with gh auth login

📄 License

MIT