pr-copilot

An MCP server that monitors GitHub pull requests through GitHub Copilot CLI. It provides a state machine-driven monitoring loop with an optional TUI dashboard viewer.

Features

• Automated PR monitoring — polls PR status (CI checks, reviews, comments, merge conflicts)
• State machine architecture — deterministic C# logic drives all decisions; the LLM agent is a thin executor
• TUI dashboard — live Terminal.Gui viewer with CI status, comments, approvals, progress bars, and deep links
• Comment handling — address, explain, or ignore review comments one-by-one or in batch
• CI failure investigation — analyze failed check logs, suggest fixes, rerun failed jobs via Azure DevOps
• Merge conflict handling — fetches and merges the latest target branch into the PR branch with git-workflow approvals and a normal push; no rebasing or force-pushes
• Auto-merge — squash merge when approved + CI green (with admin override option)
• Stale approval reminders — optionally message prior approvers when CI is green after new commits, using any messaging capability available to the agent
• After-hours awareness — pauses polling during off-hours, resumes automatically

Requirements

• GitHub CLI (gh) — authenticated with repo access
• GitHub Copilot CLI

Platform support

Platform	MCP Server	TUI Viewer
Windows (x64)	✅	✅ Requires Windows Terminal
macOS (x64)	✅	✅ Launches in iTerm (if installed) or Terminal.app
macOS (Apple Silicon)	✅	✅ Launches in iTerm (if installed) or Terminal.app

The MCP server and all PR monitoring features work on both platforms. The TUI dashboard viewer opens in a separate terminal window (Windows Terminal on Windows, iTerm/Terminal.app on macOS).

For building from source

• Stable .NET 10 SDK

Optional

• Playwright MCP server — enables clicking "Rerun failed jobs" in Azure DevOps UI. Without it, the tool falls back to triggering new builds via empty commits.

Installation

Quick install (PowerShell 7+)

# Downloads the correct binary for your platform and runs --setup
irm https://raw.githubusercontent.com/m-nash/pr-copilot/main/install.ps1 | iex

From published binary

Download the latest release for your platform from GitHub Releases, extract it, then run setup:

# Windows
PrCopilot.exe --setup

# macOS
chmod +x PrCopilot
./PrCopilot --setup

--setup will:

1. Extract SKILL.md to ~/.copilot/skills/pr-monitor/
2. Register the MCP server in ~/.copilot/mcp-config.json

From source

git clone https://github.com/m-nash/pr-copilot.git
cd pr-copilot

# Build and install using the dev script (auto-detects platform)
./Install-Debug.ps1

Or manually:

# Windows
dotnet publish PrCopilot/src/PrCopilot/PrCopilot.csproj -c Release -r win-x64 --self-contained -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -o ~/.copilot/mcp-servers/pr-copilot

# macOS (Apple Silicon)
dotnet publish PrCopilot/src/PrCopilot/PrCopilot.csproj -c Release -r osx-arm64 --self-contained -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -o ~/.copilot/mcp-servers/pr-copilot

# Then run setup
~/.copilot/mcp-servers/pr-copilot/PrCopilot --setup

Optional: Playwright MCP

For full CI rerun automation (clicking "Rerun failed jobs" in Azure DevOps):

copilot -i "mcp add playwright -- npx -y @playwright/mcp@latest --browser msedge"

Usage

In any Copilot CLI session with a PR checked out:

> monitor the pr
> monitor this pr https://github.com/owner/repo/pull/123
> monitor pr 456

The pr-monitor skill activates automatically on:

• git push to a branch with an open PR
• "monitor the PR", "watch the PR", "check PR status", etc.
• A direct PR link or PR number (assumes the current repo)

What happens

1. pr_monitor_start — fetches PR info, launches the TUI viewer, begins polling
2. Polling loop — checks CI status, reviews, comments every 30–120 seconds
3. Terminal state detected — the state machine presents choices to you:
   • 💬 New comment → Address / Explain / Handle myself
   • ❌ CI failure → Investigate / Re-run failed / Handle myself
   • ✅ Approved + CI green → Merge / Wait for more approvals
   • ⚠️ Merge conflict → Handle myself
4. After your action — monitoring resumes automatically

Starting monitoring again reconnects to an active session but initializes a fresh session after a monitor has stopped. ready re-presents a pending prompt or returns resume_pending_task with the original action and reconciliation instructions; it never marks work complete or automatically repeats a GitHub write. This also applies to multi-PR monitoring. After pushing a fix, reconnect and report the original task's completion event rather than resetting the monitor or reapplying completed work. Pending actions are retained for the lifetime of the MCP server, not across server restarts.

Concurrent starts for the same PR share one initialization with independently cancelable waits. Canceling a wait does not abort the shared startup, while an already-canceled request creates no work. Reviewer-comment explanations fetch the matching file patch across all PR file pages and use a 4,096-token sampling budget, with one 8,192-token retry if the response JSON is incomplete or invalid.

CLI flags

Flag	Description
--setup	Install SKILL.md and register MCP server
--update	Self-update to the latest GitHub release
--version	Print version and exit
--viewer --pr N --log PATH --trigger PATH	Launch TUI viewer (internal use)

Configuration

pr-copilot supports optional configuration through the args array in mcp-config.json. See docs/configuration.md for available options.

Architecture

+---------------+    MCP/JSON-RPC     +--------------------+
|  Copilot CLI  |<------------------->|   PrCopilot.exe    |
|   (Agent)     |                     |   (MCP Server)     |
+---------------+                     +--------------------+
                                      |   State Machine    |
                                      |  (C# transitions)  |
                                      +--------------------+
                                      |  GitHub CLI (gh)   |
                                      |   (API calls)      |
                                      +---------+----------+
                                                | log file
                                      +---------v----------+
                                      |    TUI Viewer      |
                                      |   (Terminal.Gui)   |
                                      +--------------------+

The state machine (MonitorTransitions) makes all decisions deterministically. The LLM agent only:

• Understands code (to address comments)
• Writes replies (to PR threads)
• Analyzes logs (to investigate CI failures)
• Follows instructions (execute what the state machine says)

Updating

# Self-update to the latest release (no need to kill running instances)
PrCopilot --update      # macOS
PrCopilot.exe --update  # Windows

The update renames the running binary, extracts the new version, and cleans up on next startup.

Development

# Build
dotnet build PrCopilot/PrCopilot.slnx

# Run tests
dotnet test PrCopilot/PrCopilot.slnx

Local install for testing

# Build and install without killing running instances (auto-detects platform)
./Install-Debug.ps1
# Then restart your Copilot CLI session

Manual macOS viewer QA (iTerm)

chmod +x scripts/manual-viewer-mac-test.sh
./scripts/manual-viewer-mac-test.sh

The script launches the viewer and feeds realistic STATUS|, TERMINAL|, RESUMING|, and STOPPED| log lines so a human can validate live UI updates, section resizing/color changes, terminal-state freeze behavior, and auto-close on stop.