@in-the-loop-labs/pair-review 1.3.3 → 1.4.0

package/README.md

@@ -12,7 +12,7 @@
 
 ## What is pair-review?
 
-pair-review is a local web application that transforms how you review code, especially code generated by AI coding agents like Claude Code, Cursor, and others. It helps you provide structured feedback and ensures quality through human oversight.
+pair-review is a local web application for keeping humans in the loop with AI coding agents. Calling it an AI code review tool would be accurate but incomplete — it supports multiple workflows beyond automated review, from reviewing agent-generated code before committing, to judging AI suggestions instead of reading every line, to using AI to guide your attention during a thorough review. You pick what fits your situation.
 
 ### Two Core Value Propositions
 
@@ -33,9 +33,58 @@ pair-review is a local web application that transforms how you review code, espe
 - **Local-First**: All data and processing happens on your machine - no cloud dependencies
 - **GitHub-Familiar UI**: Interface feels instantly familiar to GitHub users
 - **Human-in-the-Loop**: AI suggests, you decide
-- **Multiple AI Providers**: Support for Claude, Gemini, Codex, Copilot, OpenCode, and Cursor. Use your existing subscription!
+- **Multiple AI Providers**: Support for Claude, Gemini, Codex, Copilot, OpenCode, Cursor, and Pi. Use your existing subscription!
 - **Progressive**: Start simple with manual review, add AI analysis when you need it
 
+## Workflows
+
+There are no hard boundaries between these — mix and match as needed.
+
+### 1. Local Review: Human Reviews Agent-Generated Code
+
+**When to use:** You're working with a coding agent and want to review its changes before committing.
+
+This is the core feedback loop workflow. When an agent generates code, open `pair-review` to review the uncommitted changes. With the GitHub-like UI, you can add comments at specific file and line locations, then copy that formatted feedback and paste it back into whatever coding agent you're using (or use MCP/skills to read comments directly into Claude Code).
+
+Compared to giving feedback in chat, this feels like moving from a machete to a scalpel. Instead of trying to capture everything in one message, you can leave targeted comments at dozens of specific locations — and the agent addresses each one with surgical precision.
+
+**How it works:**
+1. Run `pair-review --local` to open the diff UI
+2. Review changes in a familiar GitHub-like interface
+3. Add comments with specific file and line locations
+4. Copy formatted feedback and paste into your coding agent
+5. Iterate until you're satisfied
+
+**Tips:**
+- Stage previous changes in git, then only review new modifications in the next round
+- Local mode only shows unstaged changes and untracked files (opinionated by design)
+### 2. Meta-Review: Judging AI Suggestions
+
+**When to use:** You're not going to read every line of code. Let AI be your reader.
+
+Instead of reviewing thousands of lines of code, you review a dozen AI suggestions. The AI reads the code; you review its recommendations. Each suggestion comes with enough context to evaluate it — even when you're not deeply familiar with the language or codebase.
+
+Adopt suggestions you agree with, dismiss the rest, then feed adopted suggestions back to your coding agent. This is "supervised collaboration" — you stay in the loop without getting in the weeds.
+
+**How it works:**
+1. Open `pair-review --local` or `pair-review <PR-URL>` and click **Run Analysis**
+2. AI performs three levels of review in parallel (see [Three-Level AI Analysis](#three-level-ai-analysis) below)
+3. Results are deduplicated and combined by an orchestration step
+4. Adopt suggestions you agree with, dismiss the rest
+5. Feed adopted suggestions back to your coding agent
+
+### 3. AI-Guided Review: When You're Accountable
+
+**When to use:** You're reviewing code where someone is relying on your judgment. You're still reading the code — AI helps guide your attention and articulate feedback.
+
+You're responsible for the review, but `pair-review` helps you be more thorough. Kick off the AI analysis and either wait for it to finish or start reading while it runs in the background. The AI suggestions guide you to areas worth attention and help you write clearer explanations. You can also do your own review first, then check whether the AI found the same things — a useful sanity check in both directions.
+
+**How it works:**
+1. Run AI analysis on the PR (in background or wait for results)
+2. Read through the code with AI suggestions visible
+3. Adopt suggestions you agree with, dismiss the rest, add your own comments
+4. Submit as a rich, detailed review to GitHub
+
 ## Quick Start
 
 ### Installation
@@ -165,6 +214,7 @@ pair-review supports several environment variables for customizing behavior:
 | `PAIR_REVIEW_COPILOT_CMD` | Custom command to invoke Copilot CLI | `copilot` |
 | `PAIR_REVIEW_OPENCODE_CMD` | Custom command to invoke OpenCode CLI | `opencode` |
 | `PAIR_REVIEW_CURSOR_AGENT_CMD` | Custom command to invoke Cursor Agent CLI | `agent` |
+| `PAIR_REVIEW_PI_CMD` | Custom command to invoke Pi CLI | `pi` |
 | `PAIR_REVIEW_MODEL` | Override the AI model to use (same as `--model` flag) | Provider default |
 
 **Note:** `GITHUB_TOKEN` is the standard environment variable used by many GitHub tools (gh CLI, GitHub Actions, etc.). When set, it takes precedence over the `github_token` field in the config file.
@@ -218,17 +268,18 @@ pair-review integrates with AI providers via their CLI tools:
 - **GitHub Copilot**: Uses Copilot CLI
 - **OpenCode**: Uses OpenCode CLI (requires model configuration)
 - **Cursor**: Uses Cursor Agent CLI (streaming output with sandbox mode)
+- **Pi**: Uses Pi coding agent CLI (requires model configuration)
 
 You can select your preferred provider and model in the repository settings UI.
 
 #### Built-in vs. Configurable Providers
 
-Most providers (Claude, Gemini, Codex, Copilot) come with built-in model definitions. **OpenCode is different** - it has no built-in models and requires you to configure which models to use.
+Most providers (Claude, Gemini, Codex, Copilot) come with built-in model definitions. **OpenCode and Pi are different** - they have no built-in models and require you to configure which models to use.
 
 #### Configuring Custom Models
 
 You can override provider settings and define custom models in your config file. This is useful for:
-- Adding models to OpenCode (required)
+- Adding models to OpenCode or Pi (required for these providers)
 - Overriding default commands or arguments
 - Setting provider-specific environment variables
 
@@ -330,6 +381,15 @@ pair-review's AI analysis system examines your code changes at increasing levels
 
 This progressive approach keeps analysis focused while catching issues at every scope.
 
+### Customization
+
+Tailor AI analysis to your team's standards and your current needs:
+
+- **Repo-level instructions**: Always included when generating suggestions for a specific repo. Point to codebase best practices docs, highlight common review mistakes, or include other helpful resources. Reviews will actively cite this guidance when relevant.
+- **Review-level instructions**: Customize individual reviews on the fly. Request deeper analysis with detailed code suggestions, ask for a "blockers only" final review, or adjust the focus for a particular set of changes.
+
+There's a compounding benefit: if you run `pair-review` with the same coding agent you use for development — one already configured with your rules and instructions — it will actively search for violations and enforce them. The review reflects your standards, not generic best practices.
+
 ### Review Feedback Export
 
 The killer feature for AI coding agent workflows:
@@ -552,40 +612,6 @@ npm run dev
 - **AI Integration**: CLI-based adapter pattern for multiple providers
 - **Git**: Uses git worktrees for clean PR checkout
 
-## Use Cases
-
-### 1. Reviewing AI-Generated Code
-
-You're working with a coding agent on a new feature:
-
-1. The coding agent generates code changes
-2. Run `pair-review --local` to review
-3. Add comments on issues or improvements needed
-4. Copy the markdown feedback
-5. Paste back to the agent: "Address my review feedback: [paste]"
-6. The coding agent iterates based on your comments
-7. Repeat until satisfied
-
-### 2. Team Pull Request Review
-
-Standard GitHub PR review workflow:
-
-1. Run `pair-review <PR-URL>`
-2. Optional: Trigger AI analysis for initial insights
-3. Review code, adopt useful AI suggestions
-4. Add your own expert comments
-5. Submit review to GitHub with approval status
-
-### 3. Self-Review Before Committing
-
-Before creating a PR:
-
-1. Make local changes
-2. Run `pair-review --local`
-3. Review your own changes (with or without AI)
-4. Catch issues early
-5. Commit with confidence
-
 ## FAQ
 
 **Q: Does my code get sent to the cloud?**
@@ -609,6 +635,9 @@ A: Try refreshing your browser. Many transient issues resolve with a simple page
 **Q: How do I use OpenCode as my AI provider?**
 A: OpenCode has no built-in models, so you must configure them in your `~/.pair-review/config.json`. Add a `providers.opencode.models` array with at least one model definition. See the [AI Provider Configuration](#ai-provider-configuration) section for a complete example.
 
+**Q: How do I use Pi as my AI provider?**
+A: Like OpenCode, Pi has no built-in models. Configure them in your `~/.pair-review/config.json` by adding a `providers.pi.models` array with at least one model definition. Pi supports many providers (Google, Anthropic, OpenAI, etc.) via its `--provider` and `--model` flags. See the [AI Provider Configuration](#ai-provider-configuration) section and `config.example.json` for examples.
+
 ## Contributing
 
 Contributions welcome! Please:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@in-the-loop-labs/pair-review",
-  "version": "1.3.3",
+  "version": "1.4.0",
   "description": "Your AI-powered code review partner - Close the feedback loop with AI coding agents",
   "main": "src/server.js",
   "bin": {

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pair-review",
-  "version": "1.3.3",
+  "version": "1.4.0",
   "description": "pair-review app integration — Open PRs and local changes in the pair-review web UI, run server-side AI analysis, and address review feedback. Requires the pair-review MCP server.",
   "author": {
     "name": "in-the-loop-labs",

package/plugin-code-critic/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-critic",
-  "version": "1.3.3",
+  "version": "1.4.0",
   "description": "AI-powered code review analysis — Run three-level AI analysis and implement-review-fix loops directly in your coding agent. Works standalone, no server required.",
   "author": {
     "name": "in-the-loop-labs",