@in-the-loop-labs/pair-review 2.1.0 → 2.2.0

package/README.md

@@ -195,6 +195,9 @@ pair-review --local [path]
 | `-h`, `--help` | Show help message with full CLI documentation |
 | `-l`, `--local [path]` | Review local uncommitted changes. Optional path defaults to current directory |
 | `--model <name>` | Override the AI model for any provider. Model availability depends on provider configuration. |
+| `--register` | Register `pair-review://` URL scheme handler (macOS only) |
+| `--unregister` | Unregister `pair-review://` URL scheme handler (macOS only) |
+| `--command <cmd>` | Custom CLI command for `--register` (default: `npx @in-the-loop-labs/pair-review`) |
 | `-v`, `--version` | Show version number |
 
 ### Examples
@@ -204,6 +207,8 @@ pair-review 123                        # Review PR #123 in current repo
 pair-review https://github.com/owner/repo/pull/456
 pair-review --local                    # Review uncommitted local changes
 pair-review 123 --ai                   # Auto-run AI analysis
+pair-review --register                 # Register pair-review:// URL scheme (macOS)
+pair-review --register --command "node bin/pair-review.js"  # Custom command
 ```
 
 ## Configuration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@in-the-loop-labs/pair-review",
-  "version": "2.1.0",
+  "version": "2.2.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": "2.1.0",
+  "version": "2.2.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": "2.1.0",
+  "version": "2.2.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",

package/plugin-code-critic/skills/analyze/references/level1-balanced.md

@@ -92,6 +92,15 @@ Do NOT modify files or run write commands. Analyze and report only.
   "summary": "Brief summary of findings"
 }
 
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+```suggestion
+replacement content here
+```
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
+
 ## Line Number Reference (old_or_new field)
 The "old_or_new" field indicates which line number column to use:
 - **"NEW"** (default): Use the NEW column number for:

package/plugin-code-critic/skills/analyze/references/level1-fast.md

@@ -78,6 +78,15 @@ Annotated diff tool, `cat -n`, ls, find, grep. Do NOT modify files.
   "summary": "Brief summary"
 }
 
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+```suggestion
+replacement content here
+```
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
+
 ## Line Numbers (old_or_new)
 - "NEW" (default): added [+] and context lines
 - "OLD": deleted [-] lines only

package/plugin-code-critic/skills/analyze/references/level1-thorough.md

@@ -138,6 +138,15 @@ Output JSON with this structure:
   "summary": "Brief summary of findings"
 }
 
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+```suggestion
+replacement content here
+```
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
+
 ## Line Number Reference (old_or_new field)
 The "old_or_new" field indicates which line number column to use:
 - **"NEW"** (default): Use the NEW column number. This is correct for:

package/plugin-code-critic/skills/analyze/references/level2-balanced.md

@@ -103,6 +103,15 @@ Note: You may use parallel read-only Tasks to examine multiple files simultaneou
   "summary": "Brief summary of file context findings"
 }
 
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+```suggestion
+replacement content here
+```
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
+
 ## Line Number Reference (old_or_new field)
 - **"NEW"** (default): For ADDED [+] lines and CONTEXT lines
 - **"OLD"**: ONLY for DELETED [-] lines

package/plugin-code-critic/skills/analyze/references/level2-fast.md

@@ -87,6 +87,15 @@ Annotated diff tool (preferred), `cat -n <file>`, ls, find, grep. Do NOT modify
   "summary": "Brief summary"
 }
 
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+```suggestion
+replacement content here
+```
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
+
 ## Line Numbers
 "NEW" (default): added [+] and context lines. "OLD": only deleted [-] lines.
 

package/plugin-code-critic/skills/analyze/references/level2-thorough.md

@@ -177,6 +177,15 @@ Output JSON with this structure:
   "summary": "Brief summary of file context findings"
 }
 
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+```suggestion
+replacement content here
+```
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
+
 ## old_or_new Field Reference
 Use "NEW" (the default) for added lines [+] and context lines. Use "OLD" only for deleted lines [-]. When uncertain, use "NEW".
 

package/plugin-code-critic/skills/analyze/references/level3-balanced.md

@@ -140,6 +140,15 @@ Output JSON with this structure:
   "summary": "Brief summary of how these changes connect to and impact the codebase"
 }
 
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+```suggestion
+replacement content here
+```
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
+
 ## Line Number Reference (old_or_new field)
 The "old_or_new" field indicates which line number column to use:
 - **"NEW"** (default): Use the NEW column number. This is correct for:

package/plugin-code-critic/skills/analyze/references/level3-fast.md

@@ -110,6 +110,15 @@ Output JSON with this structure:
   "summary": "Brief summary of how these changes connect to and impact the codebase"
 }
 
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+```suggestion
+replacement content here
+```
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
+
 ## Line Numbers (old_or_new)
 - **"NEW"** (default): For added lines [+] and context lines
 - **"OLD"**: Only for deleted lines [-]

package/plugin-code-critic/skills/analyze/references/level3-thorough.md

@@ -251,6 +251,15 @@ Output JSON with this structure:
   "summary": "Brief summary of how these changes connect to and impact the codebase"
 }
 
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+```suggestion
+replacement content here
+```
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
+
 ## Line Number Reference (old_or_new field)
 The "old_or_new" field indicates which line number column to use:
 - **"NEW"** (default): Use the NEW column number. This is correct for:

package/plugin-code-critic/skills/analyze/references/orchestration-balanced.md

@@ -120,6 +120,15 @@ Output JSON with this structure:
   "summary": "Brief summary of the key findings and their significance to the reviewer. Focus on WHAT was found, not HOW it was found. Do NOT mention 'orchestration', 'levels', 'merged from Level 1/2/3' etc. Write as if a single reviewer produced this analysis."
 }
 
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+```suggestion
+replacement content here
+```
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
+
 ## Line Number Reference (old_or_new field)
 The "old_or_new" field indicates which line number column to use:
 - **"NEW"** (default): Correct for ADDED lines and CONTEXT lines (unchanged lines in both versions)

package/plugin-code-critic/skills/analyze/references/orchestration-fast.md

@@ -97,6 +97,15 @@ Use "Consider...", "Worth noting..." - guidance not mandates.
   "summary": "Key findings as if from single reviewer (no mention of levels/orchestration)"
 }
 
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+```suggestion
+replacement content here
+```
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
+
 ## old_or_new
 "NEW" (default): added [+] and context lines. "OLD": deleted [-] only. Preserve from input.
 

package/plugin-code-critic/skills/analyze/references/orchestration-thorough.md

@@ -250,6 +250,15 @@ Output JSON with this structure:
   "summary": "Brief summary of the key findings and their significance to the reviewer. Focus on WHAT was found, not HOW it was found. Do NOT mention 'orchestration', 'levels', 'merged from Level 1/2/3' etc. Write as if a single reviewer produced this analysis."
 }
 
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+```suggestion
+replacement content here
+```
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
+
 ## Line Number Reference (old_or_new field)
 The "old_or_new" field indicates which line number column to use:
 - **"NEW"** (default): Use the NEW column number. This is correct for:

package/public/css/pr.css

@@ -4846,6 +4846,16 @@ tr.line-range-start .d2h-code-line-ctn {
   opacity: 0.7;
 }
 
+/* Assisted-by footer toggle (extends .remember-toggle) */
+.assisted-by-toggle {
+  margin-top: 8px;
+}
+
+.assisted-by-toggle.disabled {
+  opacity: 0.5;
+  pointer-events: none;
+}
+
 .review-type-options {
   display: flex;
   flex-direction: column;

package/public/js/components/ChatPanel.js

@@ -2827,7 +2827,7 @@ class ChatPanel {
   _handleDismissCommentClick() {
     if (this.isStreaming || !this._contextItemId) return;
     this._pendingActionContext = { type: 'dismiss-comment', itemId: this._contextItemId };
-    this.inputEl.value = 'Please delete this comment.';
+    this.inputEl.value = 'Please dismiss this comment.';
     this.sendMessage();
   }
 

package/public/js/components/ReviewModal.js

@@ -3,11 +3,24 @@
  * Review Submission Modal Component
  * Allows users to submit their review with comments to GitHub
  */
+
+const ASSISTED_BY_STORAGE_KEY = 'pair-review-assisted-by';
+const DEFAULT_ASSISTED_BY_URL = 'https://github.com/in-the-loop-labs/pair-review';
+
 class ReviewModal {
   constructor() {
     this.modal = null;
     this.isVisible = false;
     this.isSubmitting = false;
+    this.assistedByUrl = DEFAULT_ASSISTED_BY_URL;
+    fetch('/api/config')
+      .then(res => res.ok ? res.json() : null)
+      .then(data => {
+        if (data?.assisted_by_url) {
+          this.assistedByUrl = data.assisted_by_url;
+        }
+      })
+      .catch(() => {});  // Use default on failure
     this.createModal();
     this.setupEventListeners();
   }
@@ -69,6 +82,11 @@ class ReviewModal {
                 placeholder="Leave a comment about this pull request..."
                 rows="2"
               ></textarea>
+              <label class="remember-toggle assisted-by-toggle" id="assisted-by-toggle">
+                <input type="checkbox" id="assisted-by-checkbox" />
+                <span class="toggle-switch"></span>
+                <span class="toggle-label">Append pair-review footer</span>
+              </label>
             </div>
             
             <div class="review-type-section">
@@ -183,6 +201,9 @@ class ReviewModal {
       if (e.target.matches('input[name="review-event"]')) {
         window.reviewModal?.updateTextareaState();
       }
+      if (e.target.matches('#assisted-by-checkbox')) {
+        window.reviewModal?.handleAssistedByToggle();
+      }
     });
   }
 
@@ -194,6 +215,7 @@ class ReviewModal {
   updateTextareaState() {
     const textarea = this.modal?.querySelector('#review-body-modal');
     const selectedOption = this.modal?.querySelector('input[name="review-event"]:checked');
+    const toggle = this.modal?.querySelector('#assisted-by-toggle');
 
     if (!textarea || !selectedOption) return;
 
@@ -204,9 +226,15 @@ class ReviewModal {
     if (isDraft) {
       textarea.title = 'Review summary is not included with draft reviews';
       textarea.classList.add('disabled-textarea');
+      if (toggle) {
+        toggle.classList.add('disabled');
+      }
     } else {
       textarea.title = '';
       textarea.classList.remove('disabled-textarea');
+      if (toggle) {
+        toggle.classList.remove('disabled');
+      }
     }
   }
 
@@ -235,6 +263,9 @@ class ReviewModal {
     // Update textarea state (ensures it's enabled since COMMENT is selected by default)
     this.updateTextareaState();
 
+    // Restore assisted-by toggle from localStorage
+    this.restoreAssistedByToggle();
+
     // Clear any errors or warnings
     this.hideError();
     this.updateLargeReviewWarning(0);
@@ -431,6 +462,10 @@ class ReviewModal {
     if (this.isSubmitting) return;
     
     const reviewBody = this.modal.querySelector('#review-body-modal').value.trim();
+    const assistedByCheckbox = this.modal.querySelector('#assisted-by-checkbox');
+    const finalBody = assistedByCheckbox?.checked
+      ? reviewBody + this.getAssistedByFooter()
+      : reviewBody;
     const selectedOption = this.modal.querySelector('input[name="review-event"]:checked');
     const reviewEvent = selectedOption ? selectedOption.value : 'COMMENT';
     // Count BOTH line-level (.user-comment-row) and file-level (.file-comment-card.user-comment) comments
@@ -480,7 +515,7 @@ class ReviewModal {
         },
         body: JSON.stringify({
           event: reviewEvent,
-          body: reviewBody
+          body: finalBody
         })
       });
       
@@ -590,7 +625,6 @@ class ReviewModal {
     const textarea = this.modal?.querySelector('#review-body-modal');
     if (!textarea) return;
 
-    // Get AI summary from the AI panel
     const summary = window.aiPanel?.getSummary?.();
     if (!summary) {
       if (window.toast) {
@@ -613,6 +647,35 @@ class ReviewModal {
     }
   }
 
+  /**
+   * Get the "assisted by" footer string
+   */
+  getAssistedByFooter() {
+    const url = this.assistedByUrl || DEFAULT_ASSISTED_BY_URL;
+    return `\n\n---\n_Review assisted by [pair-review](${url})_`;
+  }
+
+  /**
+   * Restore the assisted-by toggle state from localStorage
+   */
+  restoreAssistedByToggle() {
+    const checkbox = this.modal?.querySelector('#assisted-by-checkbox');
+    if (!checkbox) return;
+
+    const stored = localStorage.getItem(ASSISTED_BY_STORAGE_KEY);
+    checkbox.checked = stored !== 'false';
+  }
+
+  /**
+   * Handle the assisted-by checkbox toggle
+   */
+  handleAssistedByToggle() {
+    const checkbox = this.modal?.querySelector('#assisted-by-checkbox');
+    if (!checkbox) return;
+
+    localStorage.setItem(ASSISTED_BY_STORAGE_KEY, String(checkbox.checked));
+  }
+
 }
 
 // Initialize when DOM is ready if not already initialized

package/src/ai/analyzer.js

@@ -3505,8 +3505,12 @@ File-level suggestions should NOT have a line number. They apply to the entire f
         continue;
       }
 
+      const suggestionText = suggestion.suggestion;
+      const hasSuggestionBlock = suggestionText?.trimStart().startsWith('```suggestion');
       const body = suggestion.description +
-        (suggestion.suggestion ? '\n\n**Suggestion:** ' + suggestion.suggestion : '');
+        (suggestionText
+          ? (hasSuggestionBlock ? '\n\n' + suggestionText : '\n\n**Suggestion:** ' + suggestionText)
+          : '');
 
       const isFileLevel = suggestion.is_file_level === true || suggestion.line_start === null ? 1 : 0;
       const side = suggestion.old_or_new === 'OLD' ? 'LEFT' : 'RIGHT';

package/src/ai/prompts/baseline/consolidation/balanced.js

@@ -118,6 +118,15 @@ Output JSON with this structure:
   }],
   "summary": "Brief consolidation summary. Write as if a single reviewer produced this analysis — do NOT mention 'consolidation', 'merging', or 'multiple reviewers'."
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true">

package/src/ai/prompts/baseline/consolidation/fast.js

@@ -89,6 +89,15 @@ Merge suggestions from multiple AI reviewers. Deduplicate. Resolve conflicts. Ke
   }],
   "summary": "Key findings as if from single reviewer (no mention of consolidation/merging)"
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true" tier="fast">

package/src/ai/prompts/baseline/consolidation/thorough.js

@@ -173,6 +173,15 @@ Output JSON with this structure:
   }],
   "summary": "Brief summary of the key findings and their significance. Write as if a single reviewer produced this analysis — do NOT mention 'consolidation', 'merging', or 'multiple reviewers'."
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true" tier="thorough">

package/src/ai/prompts/baseline/level1/balanced.js

@@ -119,6 +119,15 @@ Do NOT modify files or run write commands. Analyze and report only.
   }],
   "summary": "Brief summary of findings"
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true">

package/src/ai/prompts/baseline/level1/fast.js

@@ -98,6 +98,15 @@ Annotated diff tool, \`cat -n\`, ls, find, grep. Do NOT modify files.
   }],
   "summary": "Brief summary"
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true" tier="fast">

package/src/ai/prompts/baseline/level1/thorough.js

@@ -161,6 +161,15 @@ Output JSON with this structure:
   }],
   "summary": "Brief summary of findings"
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true" tier="thorough">

package/src/ai/prompts/baseline/level2/balanced.js

@@ -126,6 +126,15 @@ Note: You may use parallel read-only Tasks to examine multiple files simultaneou
   }],
   "summary": "Brief summary of file context findings"
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true">

package/src/ai/prompts/baseline/level2/fast.js

@@ -107,6 +107,15 @@ Annotated diff tool (preferred), \`cat -n <file>\`, ls, find, grep. Do NOT modif
   }],
   "summary": "Brief summary"
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true" tier="fast">

package/src/ai/prompts/baseline/level2/thorough.js

@@ -201,6 +201,15 @@ Output JSON with this structure:
   }],
   "summary": "Brief summary of file context findings"
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true" tier="thorough">

package/src/ai/prompts/baseline/level3/balanced.js

@@ -150,6 +150,15 @@ Output JSON with this structure:
   }],
   "summary": "Brief summary of how these changes connect to and impact the codebase"
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true">

package/src/ai/prompts/baseline/level3/fast.js

@@ -124,6 +124,15 @@ Output JSON with this structure:
   }],
   "summary": "Brief summary of how these changes connect to and impact the codebase"
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true" tier="fast">

package/src/ai/prompts/baseline/level3/thorough.js

@@ -268,6 +268,15 @@ Output JSON with this structure:
   }],
   "summary": "Brief summary of how these changes connect to and impact the codebase"
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true" tier="thorough">

package/src/ai/prompts/baseline/orchestration/balanced.js

@@ -140,6 +140,15 @@ Output JSON with this structure:
   }],
   "summary": "Brief summary of the key findings and their significance to the reviewer. Focus on WHAT was found, not HOW it was found. Do NOT mention 'orchestration', 'levels', 'merged from Level 1/2/3' etc. Write as if a single reviewer produced this analysis."
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true">

package/src/ai/prompts/baseline/orchestration/fast.js

@@ -120,6 +120,15 @@ Use "Consider...", "Worth noting..." - guidance not mandates.
   }],
   "summary": "Key findings as if from single reviewer (no mention of levels/orchestration)"
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true" tier="fast">

package/src/ai/prompts/baseline/orchestration/thorough.js

@@ -283,6 +283,15 @@ Output JSON with this structure:
   }],
   "summary": "Brief summary of the key findings and their significance to the reviewer. Focus on WHAT was found, not HOW it was found. Do NOT mention 'orchestration', 'levels', 'merged from Level 1/2/3' etc. Write as if a single reviewer produced this analysis."
 }
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.
 </section>
 
 <section name="diff-instructions" required="true" tier="thorough">

package/src/ai/prompts/shared/output-schema.js

@@ -148,7 +148,16 @@ function buildOutputSchemaSection(schema) {
 Output ONLY valid JSON with no additional text, explanations, or markdown code blocks. Do not wrap the JSON in \`\`\`json blocks. The response must start with { and end with }.
 
 Output JSON with this structure:
-${JSON.stringify(schema, null, 2)}`
+${JSON.stringify(schema, null, 2)}
+
+### GitHub Suggestion Syntax
+When suggesting a specific change, **embed** a GitHub suggestion block within the "suggestion" field:
+
+\`\`\`suggestion
+replacement content here
+\`\`\`
+
+The content inside the block is the complete replacement for the commented line(s). Do not include explanation inside the block — any explanation should appear as plain text outside it. For non-specific suggestions, use plain text only.`
   };
 }
 

package/src/chat/prompt-builder.js

@@ -44,6 +44,7 @@ function buildChatPrompt({ review, prData, skillPath, chatInstructions }) {
     '- **Comments** are human-curated review findings (created by the reviewer).',
     '- **Suggestions** are AI-generated findings from analysis runs.',
     '- **Workflow**: AI generates suggestions → reviewer triages (adopt, edit, or dismiss) → adopted suggestions become comments.',
+    '- **IMPORTANT**: Do NOT adopt, dismiss, or modify suggestions or comments unless the user explicitly asks you to. Your role is to discuss and explain — the reviewer decides what action to take.',
     '- **Analysis runs** are the process that produces suggestions. Each run has a provider, model, tier, and status.',
     '- **Review ID** is a stable integer identifying this review session, used in all API calls.'
   ];
@@ -69,7 +70,11 @@ function buildChatPrompt({ review, prData, skillPath, chatInstructions }) {
     'These become clickable links in the UI. Do NOT use backtick code spans for file references you want to be clickable.\n\n' +
     'Files in the diff can be referenced freely. Files outside the diff can also be referenced; ' +
     'to make them visible in the diff panel, add them as context files via the API (see skill). ' +
-    'Add context files judiciously — only when directly relevant, with focused line ranges.'
+    'Add context files judiciously — only when directly relevant, with focused line ranges.\n\n' +
+    'When the user asks to see code (e.g. "Show me…", "Where is…", "What does X look like?"), ' +
+    'add the relevant file as a context file with a focused line range so it appears in the diff panel. ' +
+    'When explaining code, prefer referencing specific line ranges (e.g. [[file:path.js:10-25]]) ' +
+    'over quoting large blocks in your response. Short inline snippets (a few lines) are fine when they clarify the explanation.'
   );
 
   // Tool usage discipline — avoid unnecessary Task delegation

package/src/config.js

@@ -24,7 +24,8 @@ const DEFAULT_CONFIG = {
   enable_chat: true,  // When true, enables the chat panel feature (requires Pi AI provider)
   chat: { enable_shortcuts: true },  // Chat panel settings (enable_shortcuts: show action shortcut buttons)
   providers: {},  // Custom provider configurations (overrides built-in defaults)
-  monorepos: {}  // Monorepo configurations: { "owner/repo": { path: "~/path/to/clone" } }
+  monorepos: {},  // Monorepo configurations: { "owner/repo": { path: "~/path/to/clone" } }
+  assisted_by_url: "https://github.com/in-the-loop-labs/pair-review"  // URL for "Review assisted by" footer link
 };
 
 /**

package/src/database.js

@@ -2193,8 +2193,12 @@ class CommentRepository {
     }
 
     for (const suggestion of normalized) {
+      const suggestionText = suggestion.suggestion;
+      const hasSuggestionBlock = suggestionText?.trimStart().startsWith('```suggestion');
       const body = suggestion.description +
-        (suggestion.suggestion ? '\n\n**Suggestion:** ' + suggestion.suggestion : '');
+        (suggestionText
+          ? (hasSuggestionBlock ? '\n\n' + suggestionText : '\n\n**Suggestion:** ' + suggestionText)
+          : '');
 
       // File-level suggestions have is_file_level=true or have null line_start
       const isFileLevel = suggestion.is_file_level === true || suggestion.line_start === null ? 1 : 0;

package/src/github/parser.js

@@ -30,7 +30,7 @@ class PRArgumentParser {
     // Check if input is a PR number
     const prNumber = parseInt(input);
     if (isNaN(prNumber) || prNumber <= 0) {
-      throw new Error('Invalid input format. Expected: PR number, GitHub URL (https://github.com/owner/repo/pull/number), or Graphite URL (https://app.graphite.com/github/pr/owner/repo/number)');
+      throw new Error('Invalid input format. Expected: PR number, GitHub URL (https://github.com/owner/repo/pull/number), Graphite URL (https://app.graphite.com/github/pr/owner/repo/number), or pair-review:// URL');
     }
 
     // Parse repository from current directory's git remote
@@ -59,6 +59,15 @@ class PRArgumentParser {
       normalizedUrl = 'https://' + normalizedUrl;
     }
 
+    // Check if input is a pair-review:// protocol URL
+    if (normalizedUrl.startsWith('pair-review://')) {
+      try {
+        return this.parseProtocolURL(normalizedUrl);
+      } catch (e) {
+        return null;
+      }
+    }
+
     // Check if input is a GitHub URL
     if (normalizedUrl.startsWith('https://github.com/')) {
       try {
@@ -114,6 +123,22 @@ class PRArgumentParser {
     return this._createPRInfo(owner, repo, numberStr, 'Graphite');
   }
 
+  /**
+   * Parse pair-review:// protocol URL to extract owner, repo, and PR number
+   * @param {string} url - Protocol URL (e.g., pair-review://pr/owner/repo/123)
+   * @returns {Object} Parsed information { owner, repo, number }
+   */
+  parseProtocolURL(url) {
+    const match = url.match(/^pair-review:\/\/pr\/([^\/]+)\/([^\/]+)\/(\d+)(?:\/.*)?$/);
+
+    if (!match) {
+      throw new Error('Invalid pair-review:// URL format. Expected: pair-review://pr/owner/repo/number');
+    }
+
+    const [, owner, repo, numberStr] = match;
+    return this._createPRInfo(owner, repo, numberStr, 'pair-review://');
+  }
+
   /**
    * Create and validate PR info object from parsed components
    * @param {string} owner - Repository owner
@@ -129,7 +154,9 @@ class PRArgumentParser {
     if (isNaN(number) || number <= 0) {
       const exampleUrl = source === 'GitHub'
         ? 'https://github.com/owner/repo/pull/number'
-        : 'https://app.graphite.com/github/pr/owner/repo/number';
+        : source === 'pair-review://'
+          ? 'pair-review://pr/owner/repo/number'
+          : 'https://app.graphite.com/github/pr/owner/repo/number';
       throw new Error(`Invalid ${source} URL format. Expected: ${exampleUrl}`);
     }
 

package/src/main.js

@@ -16,6 +16,7 @@ const simpleGit = require('simple-git');
 const { getGeneratedFilePatterns } = require('./git/gitattributes');
 const { getEmoji: getCategoryEmoji } = require('./utils/category-emoji');
 const open = (...args) => import('open').then(({default: open}) => open(...args));
+const { registerProtocolHandler, unregisterProtocolHandler } = require('./protocol-handler');
 
 let db = null;
 
@@ -117,6 +118,9 @@ OPTIONS:
                             (automatic in GitHub Actions)
     --yolo                  Allow AI providers full system access (skip read-only
                             restrictions). Analogous to --dangerously-skip-permissions
+    --register [--command <cmd>]  Register pair-review:// URL scheme handler (macOS)
+                                Default command: npx @in-the-loop-labs/pair-review
+    --unregister                Unregister pair-review:// URL scheme handler (macOS)
     -v, --version           Show version number and exit
 
 EXAMPLES:
@@ -125,6 +129,8 @@ EXAMPLES:
     pair-review --local                # Review uncommitted local changes
     pair-review 123 --ai               # Auto-run AI analysis
     pair-review --ai-review            # CI mode: auto-detect PR, submit review
+    pair-review --register                     # Register URL scheme handler
+    pair-review --register --command "node bin/pair-review.js"  # Custom command
 
 ENVIRONMENT VARIABLES:
     GITHUB_TOKEN            GitHub Personal Access Token (takes precedence over config file)
@@ -188,6 +194,9 @@ const KNOWN_FLAGS = new Set([
   '-l', '--local',
   '--mcp',
   '--model',
+  '--register',
+  '--unregister',
+  '--command',
   '--use-checkout',
   '--yolo',
   '-v', '--version'
@@ -243,9 +252,14 @@ function parseArgs(args) {
         i++; // Skip next argument since we consumed it
       }
       // localPath will be resolved to cwd if not provided
-    } else if (arg === '--configure' || arg === '-h' || arg === '--help' || arg === '--mcp' || arg === '-v' || arg === '--version') {
+    } else if (arg === '--configure' || arg === '-h' || arg === '--help' || arg === '--mcp' || arg === '-v' || arg === '--version' || arg === '--register' || arg === '--unregister') {
       // Skip flags that are handled earlier in main()
       continue;
+    } else if (arg === '--command') {
+      // --command flag consumed by --register handler, skip it and its value
+      if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
+        i++; // Skip the next argument (the command value)
+      }
     } else if (arg.startsWith('-')) {
       // Unknown flag - collect for error reporting
       unknownFlags.push(arg);
@@ -346,6 +360,26 @@ AI PROVIDERS:
       process.exit(0);
     }
 
+    // Handle protocol handler registration
+    if (args.includes('--register')) {
+      const cmdIdx = args.indexOf('--command');
+      let command;
+      if (cmdIdx !== -1) {
+        if (cmdIdx + 1 < args.length && !args[cmdIdx + 1].startsWith('-')) {
+          command = args[cmdIdx + 1];
+        } else {
+          throw new Error('--command flag requires a command string');
+        }
+      }
+      await registerProtocolHandler({ command });
+      process.exit(0);
+    }
+
+    if (args.includes('--unregister')) {
+      await unregisterProtocolHandler();
+      process.exit(0);
+    }
+
     // Load configuration
     const { config, isFirstRun } = await loadConfig();
 
@@ -466,8 +500,6 @@ AI PROVIDERS:
  * @param {Object} flags - Parsed command line flags
  */
 async function handlePullRequest(args, config, db, flags = {}) {
-  let prInfo = null; // Declare prInfo outside try block for error handling
-  
   try {
     // Get GitHub token (env var takes precedence over config)
     const githubToken = getGitHubToken(config);
@@ -477,156 +509,36 @@ async function handlePullRequest(args, config, db, flags = {}) {
 
     // Parse PR arguments
     const parser = new PRArgumentParser();
-    prInfo = await parser.parsePRArguments(args);
-
-    console.log(`Processing pull request #${prInfo.number} from ${prInfo.owner}/${prInfo.repo}`);
-
-    // Create GitHub client and verify repository access
-    const githubClient = new GitHubClient(githubToken);
-    const repoExists = await githubClient.repositoryExists(prInfo.owner, prInfo.repo);
-    if (!repoExists) {
-      throw new Error(`Repository ${prInfo.owner}/${prInfo.repo} not found or not accessible`);
-    }
+    const prInfo = await parser.parsePRArguments(args);
 
-    // Fetch PR data from GitHub
-    console.log('Fetching pull request data from GitHub...');
-    const prData = await githubClient.fetchPullRequest(prInfo.owner, prInfo.repo, prInfo.number);
-
-    // Determine repository path: only use cwd if it matches the target repo
+    // Register cwd as known repo path if it matches the target repo
     const currentDir = parser.getCurrentDirectory();
     const isMatchingRepo = await parser.isMatchingRepository(currentDir, prInfo.owner, prInfo.repo);
-    const repository = normalizeRepository(prInfo.owner, prInfo.repo);
-
-    let repositoryPath;
-    let worktreeSourcePath;
-    let checkoutScript;
-    let checkoutTimeout;
-    let worktreeConfig = null;
     if (isMatchingRepo) {
-      // Current directory is a checkout of the target repository
-      repositoryPath = currentDir;
-      // Register the known repository location for future web UI usage
       await registerRepositoryLocation(db, currentDir, prInfo.owner, prInfo.repo);
-
-      // Resolve monorepo config options (checkout_script, worktree_directory, worktree_name_template)
-      // even when running from inside the target repo, so they are not silently ignored.
-      const resolved = resolveMonorepoOptions(config, repository);
-      checkoutScript = resolved.checkoutScript;
-      checkoutTimeout = resolved.checkoutTimeout;
-      worktreeConfig = resolved.worktreeConfig;
-    } else {
-      // Current directory is not the target repository - find or clone it
-      console.log(`Current directory is not a checkout of ${prInfo.owner}/${prInfo.repo}, locating repository...`);
-      const result = await findRepositoryPath({
-        db,
-        owner: prInfo.owner,
-        repo: prInfo.repo,
-        repository,
-        prNumber: prInfo.number,
-        config,
-        onProgress: (progress) => {
-          if (progress.message) {
-            console.log(progress.message);
-          }
-        }
-      });
-      repositoryPath = result.repositoryPath;
-      worktreeSourcePath = result.worktreeSourcePath;
-      checkoutScript = result.checkoutScript;
-      checkoutTimeout = result.checkoutTimeout;
-      worktreeConfig = result.worktreeConfig;
     }
 
-    // Setup git worktree
-    console.log('Setting up git worktree...');
-    const worktreeManager = new GitWorktreeManager(db, worktreeConfig || {});
-    const worktreePath = await worktreeManager.createWorktreeForPR(prInfo, prData, repositoryPath, {
-      worktreeSourcePath,
-      checkoutScript,
-      checkoutTimeout
-    });
-
-    // Generate unified diff
-    console.log('Generating unified diff...');
-    const diff = await worktreeManager.generateUnifiedDiff(worktreePath, prData);
-    const changedFiles = await worktreeManager.getChangedFiles(worktreePath, prData);
+    // Set model override if provided via CLI flag
+    if (flags.model) {
+      process.env.PAIR_REVIEW_MODEL = flags.model;
+    }
 
-    // Store PR data in database
-    console.log('Storing pull request data...');
-    await storePRData(db, prInfo, prData, diff, changedFiles, worktreePath);
+    // Start server and open browser to setup page
+    const port = await startServer(db);
 
-    // Start server with PR context
-    console.log('Starting server...');
-    const port = await startServerWithPRContext(config, prInfo, flags);
+    // Async cleanup of stale worktrees (don't block startup)
+    cleanupStaleWorktreesAsync(config);
 
-    // Trigger AI analysis server-side if --ai flag is present
+    let url = `http://localhost:${port}/pr/${prInfo.owner}/${prInfo.repo}/${prInfo.number}`;
     if (flags.ai) {
-      console.log('Starting AI analysis...');
-
-      // Wait for server to be ready with retry logic
-      const maxRetries = 5;
-      const retryDelay = 200; // ms
-      let lastError;
-
-      for (let attempt = 1; attempt <= maxRetries; attempt++) {
-        try {
-          // Add small delay to ensure server is fully initialized
-          if (attempt > 1) {
-            await new Promise(resolve => setTimeout(resolve, retryDelay * attempt));
-          }
-
-          const response = await fetch(`http://localhost:${port}/api/pr/${prInfo.owner}/${prInfo.repo}/${prInfo.number}/analyses`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' }
-          });
-
-          if (response.ok) {
-            const result = await response.json();
-            console.log(`AI analysis started (ID: ${result.analysisId})`);
-            break; // Success, exit retry loop
-          } else {
-            lastError = `Server responded with ${response.status}: ${await response.text()}`;
-            if (attempt === maxRetries) {
-              console.warn('Failed to start AI analysis:', lastError);
-            }
-          }
-        } catch (error) {
-          lastError = error.message;
-          if (attempt === maxRetries) {
-            console.warn('Could not start AI analysis after', maxRetries, 'attempts:', lastError);
-          }
-        }
-      }
+      url += '?analyze=true';
     }
 
-    // Open browser to PR view
-    const url = `http://localhost:${port}/pr/${prInfo.owner}/${prInfo.repo}/${prInfo.number}`;
-
     console.log(`Opening browser to: ${url}`);
     await open(url);
 
   } catch (error) {
-    // Provide cleaner error messages for common issues
-    if (error.message && error.message.includes('not found in repository')) {
-      if (prInfo) {
-        console.error(`\n❌ Pull request #${prInfo.number} does not exist in ${prInfo.owner}/${prInfo.repo}`);
-      } else {
-        console.error(`\n❌ ${error.message}`);
-      }
-      console.error('Please check the PR number and try again.\n');
-    } else if (error.message && error.message.includes('authentication failed')) {
-      console.error('\n❌ GitHub authentication failed');
-      console.error('Please check your token in ~/.pair-review/config.json\n');
-    } else if (error.message && error.message.includes('Repository') && error.message.includes('not found')) {
-      console.error(`\n❌ ${error.message}`);
-      console.error('Please check the repository name and your access permissions.\n');
-    } else if (error.message && error.message.includes('Network error')) {
-      console.error('\n❌ Network connection error');
-      console.error('Please check your internet connection and try again.\n');
-    } else {
-      // For other errors, show a clean message without stack trace
-      console.error(`\n❌ Error: ${error.message}\n`);
-    }
+    console.error(`\n❌ Error: ${error.message}\n`);
     process.exit(1);
   }
 }
@@ -647,36 +559,6 @@ async function startServerOnly(config) {
   await open(url);
 }
 
-/**
- * Start server with PR context
- * @param {Object} config - Application configuration
- * @param {Object} prInfo - PR information
- * @param {Object} flags - Command line flags
- * @returns {Promise<number>} Server port
- */
-async function startServerWithPRContext(config, prInfo, flags = {}) {
-  // Set environment variable for PR context
-  process.env.PAIR_REVIEW_PR = JSON.stringify(prInfo);
-
-  // Set environment variable for auto-AI flag
-  if (flags.ai) {
-    process.env.PAIR_REVIEW_AUTO_AI = 'true';
-  }
-
-  // Set environment variable for model override (CLI takes priority)
-  if (flags.model) {
-    process.env.PAIR_REVIEW_MODEL = flags.model;
-  }
-
-  const { startServer } = require('./server');
-  const actualPort = await startServer(db);
-
-  // Async cleanup of stale worktrees (don't block startup)
-  cleanupStaleWorktreesAsync(config);
-
-  // Return the actual port the server started on
-  return actualPort;
-}
 
 /**
  * Format AI suggestion with emoji and category prefix

package/src/protocol-handler.js

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { getConfigDir } = require('./config');
+const logger = require('./utils/logger');
+
+const LSREGISTER = '/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister';
+
+// Default dependencies (overridable for testing)
+const defaults = {
+  fs,
+  execSync,
+  getConfigDir,
+  logger,
+};
+
+/**
+ * Register a macOS custom URL scheme handler for pair-review://
+ * Creates an AppleScript .app that forwards URLs to the pair-review CLI.
+ *
+ * @param {object} [options]
+ * @param {string} [options.command] - CLI command to invoke (default: npx @in-the-loop-labs/pair-review)
+ * @param {object} [options._deps] - Internal: dependency overrides for testing
+ */
+function registerProtocolHandler({ command, _deps } = {}) {
+  const deps = { ...defaults, ..._deps };
+
+  if (process.platform !== 'darwin') {
+    deps.logger.warn('Protocol handler registration is only supported on macOS');
+    return;
+  }
+
+  const shell = process.env.SHELL || '/bin/zsh';
+  const resolvedCommand = command || 'npx @in-the-loop-labs/pair-review';
+
+  // Escape characters special inside AppleScript double-quoted strings
+  const escapeAS = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  const safeShell = escapeAS(shell);
+  const safeCommand = escapeAS(resolvedCommand);
+
+  const appleScriptSource = [
+    'on run',
+    '\t-- No-op: launched directly without a URL',
+    'end run',
+    '',
+    'on open location theURL',
+    `\tdo shell script "${safeShell} -l -c \\"${safeCommand} " & quoted form of theURL & " > /dev/null 2>&1 &\\""`,
+    'end open location',
+  ].join('\n');
+
+  const appPath = path.join(deps.getConfigDir(), 'PairReview.app');
+
+  // Remove existing .app if present
+  deps.fs.rmSync(appPath, { recursive: true, force: true });
+
+  // Compile the AppleScript into an .app bundle
+  deps.execSync(`osacompile -o "${appPath}"`, { input: appleScriptSource });
+
+  // Mutate Info.plist to declare the URL scheme
+  const plistPath = path.join(appPath, 'Contents', 'Info.plist');
+  let plist = deps.fs.readFileSync(plistPath, 'utf-8');
+
+  const urlSchemeEntries = [
+    '\t<key>CFBundleIdentifier</key>',
+    '\t<string>com.pair-review.launcher</string>',
+    '\t<key>CFBundleURLTypes</key>',
+    '\t<array>',
+    '\t\t<dict>',
+    '\t\t\t<key>CFBundleURLName</key>',
+    '\t\t\t<string>pair-review URL</string>',
+    '\t\t\t<key>CFBundleURLSchemes</key>',
+    '\t\t\t<array>',
+    '\t\t\t\t<string>pair-review</string>',
+    '\t\t\t</array>',
+    '\t\t</dict>',
+    '\t</array>',
+  ].join('\n');
+
+  // Insert before the closing </dict> that precedes </plist>
+  plist = plist.replace('</dict>\n</plist>', `${urlSchemeEntries}\n</dict>\n</plist>`);
+  deps.fs.writeFileSync(plistPath, plist);
+
+  deps.execSync(`"${LSREGISTER}" -R -f "${appPath}"`);
+
+  // console.log intentional: CLI output, not server-side (see CLAUDE.md logging convention)
+  console.log('Registered pair-review:// URL scheme handler');
+  console.log(`Command: ${shell} -l -c '${resolvedCommand} <url>'`);
+}
+
+/**
+ * Unregister the macOS custom URL scheme handler for pair-review://
+ * Removes the .app bundle and deregisters from Launch Services.
+ *
+ * @param {object} [options]
+ * @param {object} [options._deps] - Internal: dependency overrides for testing
+ */
+function unregisterProtocolHandler({ _deps } = {}) {
+  const deps = { ...defaults, ..._deps };
+
+  if (process.platform !== 'darwin') {
+    deps.logger.warn('Protocol handler registration is only supported on macOS');
+    return;
+  }
+
+  const appPath = path.join(deps.getConfigDir(), 'PairReview.app');
+
+  // Attempt to deregister from Launch Services (may fail if not registered)
+  try {
+    deps.execSync(`"${LSREGISTER}" -u "${appPath}"`);
+  } catch {
+    // Ignore — handler may not be registered
+  }
+
+  // Remove the .app bundle
+  deps.fs.rmSync(appPath, { recursive: true, force: true });
+
+  // console.log intentional: CLI output, not server-side (see CLAUDE.md logging convention)
+  console.log('Unregistered pair-review:// URL scheme handler');
+}
+
+module.exports = { registerProtocolHandler, unregisterProtocolHandler };

package/src/routes/config.js

@@ -40,7 +40,8 @@ router.get('/api/config', (req, res) => {
     is_running_via_npx: isRunningViaNpx(),
     enable_chat: config.enable_chat !== false,
     chat_enable_shortcuts: config.chat?.enable_shortcuts !== false,
-    pi_available: getCachedAvailability('pi')?.available || false
+    pi_available: getCachedAvailability('pi')?.available || false,
+    assisted_by_url: config.assisted_by_url || 'https://github.com/in-the-loop-labs/pair-review'
   });
 });