@in-the-loop-labs/pair-review 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@in-the-loop-labs/pair-review",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Your AI-powered code review partner - Close the feedback loop with AI coding agents",
   "main": "src/server.js",
   "bin": {
@@ -30,7 +30,7 @@
     "test:e2e:debug": "playwright test --debug",
     "generate:skill-prompts": "node scripts/generate-skill-prompts.js",
     "changeset": "changeset",
-    "version": "changeset version && node scripts/sync-plugin-versions.js && git add package.json package-lock.json CHANGELOG.md .changeset .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin-code-critic/.claude-plugin/plugin.json && git commit -m 'RELEASING: Bump versions'",
+    "version": "changeset version && npm install --package-lock-only && node scripts/sync-plugin-versions.js && git add package.json package-lock.json CHANGELOG.md .changeset .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin-code-critic/.claude-plugin/plugin.json && git commit -m 'RELEASING: Bump versions'",
     "release": "npm whoami > /dev/null || { echo 'Error: Not logged in to npm. Run: npm login'; exit 1; } && npm run version && changeset tag && npm publish && git push && git push --tags"
   },
   "keywords": [

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

@@ -1,6 +1,6 @@
 {
   "name": "pair-review",
-  "version": "1.2.1",
+  "version": "1.3.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.2.1",
+  "version": "1.3.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/level3-balanced.md

@@ -96,6 +96,20 @@ You have READ-ONLY access to the codebase:
 
 You may use parallel read-only Tasks to explore different areas of the codebase if helpful.
 
+## Monorepo / Sparse Checkout Considerations
+
+If this repository uses sparse-checkout, only a subset of directories may be checked out. You can check by running:
+```
+git sparse-checkout list
+```
+
+If sparse-checkout is active and you need to examine code outside the checked-out directories to understand dependencies, patterns, or impacts, you can expand the checkout:
+```
+git sparse-checkout add <directory>
+```
+
+This is non-destructive and only adds to what's visible in the worktree.
+
 ## Output Format
 
 **>>> CRITICAL: Output ONLY valid JSON. No markdown, no ```json blocks. Start with { end with }. <<<**

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

@@ -68,6 +68,20 @@ Focus on relationships between changed code and existing patterns.
 
 Do NOT modify files.
 
+## Monorepo / Sparse Checkout Considerations
+
+If this repository uses sparse-checkout, only a subset of directories may be checked out. You can check by running:
+```
+git sparse-checkout list
+```
+
+If sparse-checkout is active and you need to examine code outside the checked-out directories to understand dependencies, patterns, or impacts, you can expand the checkout:
+```
+git sparse-checkout add <directory>
+```
+
+This is non-destructive and only adds to what's visible in the worktree.
+
 ## Output Format
 
 **>>> CRITICAL: Output ONLY valid JSON. No markdown, no ```json blocks. Start with { end with }. <<<**

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

@@ -207,6 +207,20 @@ Note: You may optionally use parallel read-only Tasks to explore different areas
 - Tracing dependencies across multiple files
 - Analyzing test coverage in parallel with main code analysis
 
+## Monorepo / Sparse Checkout Considerations
+
+If this repository uses sparse-checkout, only a subset of directories may be checked out. You can check by running:
+```
+git sparse-checkout list
+```
+
+If sparse-checkout is active and you need to examine code outside the checked-out directories to understand dependencies, patterns, or impacts, you can expand the checkout:
+```
+git sparse-checkout add <directory>
+```
+
+This is non-destructive and only adds to what's visible in the worktree.
+
 ## Output Format
 
 **>>> CRITICAL: Output ONLY valid JSON. No markdown, no ```json blocks. Start with { end with }. <<<**

package/src/ai/analyzer.js

@@ -20,6 +20,8 @@ const {
 const { registerProcess, isAnalysisCancelled, CancellationError } = require('../routes/shared');
 const { AnalysisRunRepository } = require('../database');
 const { mergeInstructions } = require('../utils/instructions');
+const { GitWorktreeManager } = require('../git/worktree');
+const { buildSparseCheckoutGuidance } = require('./prompts/sparse-checkout-guidance');
 
 class Analyzer {
   /**
@@ -33,6 +35,18 @@ class Analyzer {
     this.provider = provider;
     this.db = database;
     this.testContextCache = new Map(); // Cache test detection results per worktree
+    this._worktreeManager = null; // Lazy-initialized for sparse-checkout queries
+  }
+
+  /**
+   * Get or create worktree manager instance (lazy initialization)
+   * @returns {GitWorktreeManager}
+   */
+  _getWorktreeManager() {
+    if (!this._worktreeManager) {
+      this._worktreeManager = new GitWorktreeManager();
+    }
+    return this._worktreeManager;
   }
 
   /**
@@ -462,6 +476,23 @@ class Analyzer {
     return `${scriptCommand}${cwdOption}`;
   }
 
+  /**
+   * Build sparse-checkout guidance if applicable
+   * @param {string} worktreePath - Path to the worktree
+   * @returns {Promise<string>} Guidance text or empty string
+   */
+  async buildSparseCheckoutGuidanceSection(worktreePath) {
+    const worktreeManager = this._getWorktreeManager();
+    const isEnabled = await worktreeManager.isSparseCheckoutEnabled(worktreePath);
+
+    if (!isEnabled) {
+      return '';
+    }
+
+    const patterns = await worktreeManager.getSparseCheckoutPatterns(worktreePath);
+    return buildSparseCheckoutGuidance({ patterns });
+  }
+
   /**
    * Build the section of the prompt that includes custom review instructions
    * @param {string} customInstructions - Custom instructions text
@@ -1796,7 +1827,7 @@ If you are unsure, use "NEW" - it is correct for the vast majority of suggestion
 
       // Build the Level 3 prompt with test context
       updateProgress('Building prompt for AI to analyze codebase impact');
-      const prompt = this.buildLevel3Prompt(prId, worktreePath, prMetadata, testingContext, generatedPatterns, customInstructions, validFiles, tier);
+      const prompt = await this.buildLevel3Prompt(prId, worktreePath, prMetadata, testingContext, generatedPatterns, customInstructions, validFiles, tier);
 
       // Execute Claude CLI for Level 3 analysis
       updateProgress('Running AI to analyze codebase-wide implications');
@@ -2152,7 +2183,7 @@ If you are unsure, use "NEW" - it is correct for the vast majority of suggestion
     }
   }
 
-  buildLevel3Prompt(prId, worktreePath, prMetadata, testingContext = null, generatedPatterns = [], customInstructions = null, changedFiles = [], tier = 'balanced') {
+  async buildLevel3Prompt(prId, worktreePath, prMetadata, testingContext = null, generatedPatterns = [], customInstructions = null, changedFiles = [], tier = 'balanced') {
     logger.debug(`[Level 3] Building prompt with tier: ${tier}`);
     // Try new prompt architecture first
     const promptBuilder = getPromptBuilder('level3', tier, this.provider);
@@ -2175,6 +2206,7 @@ If you are unsure, use "NEW" - it is correct for the vast majority of suggestion
         prContext: this.buildPRContextSection(prMetadata, criticalNote),
         customInstructions: this.buildCustomInstructionsSection(customInstructions),
         lineNumberGuidance: this.buildLineNumberGuidance(worktreePath),
+        sparseCheckoutGuidance: await this.buildSparseCheckoutGuidanceSection(worktreePath),
         generatedFiles: this.buildGeneratedFilesExclusionSection(generatedPatterns),
         changedFiles: formatValidFiles(changedFiles),
         testingGuidance: this.buildTestAnalysisSection(testingContext)

package/src/ai/claude-provider.js

@@ -104,6 +104,7 @@ class ClaudeProvider extends AIProvider {
         'Bash(git status*)',
         'Bash(git branch*)',
         'Bash(git rev-parse*)',
+        'Bash(git sparse-checkout*)',
         'Bash(*git-diff-lines*)',
         'Bash(cat *)',
         'Bash(ls *)',
@@ -658,6 +659,10 @@ class ClaudeProvider extends AIProvider {
       const command = useShell ? `${this.claudeCmd} --version` : this.claudeCmd;
       const args = useShell ? [] : ['--version'];
 
+      // Log the actual command for debugging config/override issues
+      const fullCmd = useShell ? command : `${command} ${args.join(' ')}`;
+      logger.debug(`Claude availability check: ${fullCmd}`);
+
       const claude = spawn(command, args, {
         env: {
           ...process.env,

package/src/ai/codex-provider.js

@@ -586,6 +586,7 @@ class CodexProvider extends AIProvider {
 
   /**
    * Test if Codex CLI is available
+   * Uses fast `--version` check instead of running a prompt.
    * Uses the command configured in the instance (respects ENV > config > default precedence)
    * @returns {Promise<boolean>}
    */
@@ -598,6 +599,10 @@ class CodexProvider extends AIProvider {
       const command = useShell ? `${this.codexCmd} --version` : this.codexCmd;
       const args = useShell ? [] : ['--version'];
 
+      // Log the actual command for debugging config/override issues
+      const fullCmd = useShell ? command : `${command} ${args.join(' ')}`;
+      logger.debug(`Codex availability check: ${fullCmd}`);
+
       const codex = spawn(command, args, {
         env: {
           ...process.env,
@@ -607,20 +612,36 @@ class CodexProvider extends AIProvider {
       });
 
       let stdout = '';
+      let stderr = '';
       let settled = false;
 
+      // Timeout guard: if the CLI hangs, resolve false
+      const availabilityTimeout = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        logger.warn('Codex CLI availability check timed out after 10s');
+        try { codex.kill(); } catch { /* ignore */ }
+        resolve(false);
+      }, 10000);
+
       codex.stdout.on('data', (data) => {
         stdout += data.toString();
       });
 
+      codex.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+
       codex.on('close', (code) => {
         if (settled) return;
         settled = true;
-        if (code === 0 && stdout.includes('codex')) {
+        clearTimeout(availabilityTimeout);
+        if (code === 0) {
           logger.info(`Codex CLI available: ${stdout.trim()}`);
           resolve(true);
         } else {
-          logger.warn('Codex CLI not available or returned unexpected output');
+          const stderrMsg = stderr.trim() ? `: ${stderr.trim()}` : '';
+          logger.warn(`Codex CLI not available or returned unexpected output (exit code ${code})${stderrMsg}`);
           resolve(false);
         }
       });
@@ -628,6 +649,7 @@ class CodexProvider extends AIProvider {
       codex.on('error', (error) => {
         if (settled) return;
         settled = true;
+        clearTimeout(availabilityTimeout);
         logger.warn(`Codex CLI not available: ${error.message}`);
         resolve(false);
       });

package/src/ai/copilot-provider.js

@@ -113,6 +113,7 @@ class CopilotProvider extends AIProvider {
           '--allow-tool', 'shell(git status)',
           '--allow-tool', 'shell(git branch)',
           '--allow-tool', 'shell(git rev-parse)',
+          '--allow-tool', 'shell(git sparse-checkout)',
           // Custom tool for annotated diff line mapping (matches both direct and path invocations)
           '--allow-tool', 'shell(git-diff-lines)',
           '--allow-tool', 'shell(*/git-diff-lines)',  // Absolute path invocation
@@ -386,6 +387,10 @@ class CopilotProvider extends AIProvider {
       const command = useShell ? `${this.copilotCmd} --version` : this.copilotCmd;
       const args = useShell ? [] : ['--version'];
 
+      // Log the actual command for debugging config/override issues
+      const fullCmd = useShell ? command : `${command} ${args.join(' ')}`;
+      logger.debug(`Copilot availability check: ${fullCmd}`);
+
       const copilot = spawn(command, args, {
         env: {
           ...process.env,

package/src/ai/cursor-agent-provider.js

@@ -682,6 +682,10 @@ class CursorAgentProvider extends AIProvider {
       const command = useShell ? `${this.agentCmd} --version` : this.agentCmd;
       const args = useShell ? [] : ['--version'];
 
+      // Log the actual command for debugging config/override issues
+      const fullCmd = useShell ? command : `${command} ${args.join(' ')}`;
+      logger.debug(`Cursor Agent availability check: ${fullCmd}`);
+
       const agent = spawn(command, args, {
         env: {
           ...process.env,

package/src/ai/gemini-provider.js

@@ -128,6 +128,7 @@ class GeminiProvider extends AIProvider {
         'run_shell_command(git status)',
         'run_shell_command(git branch)',
         'run_shell_command(git rev-parse)',
+        'run_shell_command(git sparse-checkout)',
         // Read-only shell commands
         'run_shell_command(ls)',           // Directory listing
         'run_shell_command(cat)',          // File content viewing
@@ -636,6 +637,10 @@ class GeminiProvider extends AIProvider {
       const command = useShell ? `${this.geminiCmd} --version` : this.geminiCmd;
       const args = useShell ? [] : ['--version'];
 
+      // Log the actual command for debugging config/override issues
+      const fullCmd = useShell ? command : `${command} ${args.join(' ')}`;
+      logger.debug(`Gemini availability check: ${fullCmd}`);
+
       const gemini = spawn(command, args, {
         env: {
           ...process.env,

package/src/ai/opencode-provider.js

@@ -575,6 +575,10 @@ class OpenCodeProvider extends AIProvider {
       const command = useShell ? `${this.opencodeCmd} --version` : this.opencodeCmd;
       const args = useShell ? [] : ['--version'];
 
+      // Log the actual command for debugging config/override issues
+      const fullCmd = useShell ? command : `${command} ${args.join(' ')}`;
+      logger.debug(`OpenCode availability check: ${fullCmd}`);
+
       const opencode = spawn(command, args, {
         env: {
           ...process.env,

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

@@ -35,7 +35,7 @@ const taggedPrompt = `<section name="role" required="true">
 {{prContext}}
 </section>
 
-<section name="custom-instructions" optional="true">
+<section name="custom-instructions" optional="true" tier="fast,balanced,thorough">
 {{customInstructions}}
 </section>
 
@@ -47,7 +47,7 @@ const taggedPrompt = `<section name="role" required="true">
 {{lineNumberGuidance}}
 </section>
 
-<section name="generated-files" optional="true">
+<section name="generated-files" optional="true" tier="fast,balanced,thorough">
 {{generatedFiles}}
 </section>
 
@@ -116,6 +116,10 @@ You have READ-ONLY access to the codebase:
 You may use parallel read-only Tasks to explore different areas of the codebase if helpful.
 </section>
 
+<section name="sparse-checkout" optional="true" tier="fast,balanced,thorough">
+{{sparseCheckoutGuidance}}
+</section>
+
 <section name="output-schema" locked="true">
 ## Output Format
 
@@ -203,21 +207,22 @@ File-level suggestions should NOT have a line number. They apply to the entire f
  * Used for parsing and validation
  */
 const sections = [
-  { name: 'role', required: true },
+  { name: 'role', required: true, tier: ['balanced'] },
   { name: 'pr-context', locked: true },
-  { name: 'custom-instructions', optional: true },
-  { name: 'level-header', required: true },
-  { name: 'line-number-guidance', required: true },
-  { name: 'generated-files', optional: true },
+  { name: 'custom-instructions', optional: true, tier: ['fast', 'balanced', 'thorough'] },
+  { name: 'level-header', required: true, tier: ['balanced'] },
+  { name: 'line-number-guidance', required: true, tier: ['balanced'] },
+  { name: 'generated-files', optional: true, tier: ['fast', 'balanced', 'thorough'] },
   { name: 'changed-files', locked: true },
-  { name: 'purpose', required: true },
-  { name: 'analysis-process', required: true },
-  { name: 'focus-areas', required: true },
-  { name: 'available-commands', required: true },
+  { name: 'purpose', required: true, tier: ['balanced'] },
+  { name: 'analysis-process', required: true, tier: ['balanced'] },
+  { name: 'focus-areas', required: true, tier: ['balanced'] },
+  { name: 'available-commands', required: true, tier: ['balanced'] },
+  { name: 'sparse-checkout', optional: true, tier: ['fast', 'balanced', 'thorough'] },
   { name: 'output-schema', locked: true },
-  { name: 'diff-instructions', required: true },
-  { name: 'file-level-guidance', optional: true },
-  { name: 'guidelines', required: true }
+  { name: 'diff-instructions', required: true, tier: ['balanced'] },
+  { name: 'file-level-guidance', optional: true, tier: ['balanced', 'thorough'] },
+  { name: 'guidelines', required: true, tier: ['balanced'] }
 ];
 
 /**
@@ -235,6 +240,7 @@ const defaultOrder = [
   'analysis-process',
   'focus-areas',
   'available-commands',
+  'sparse-checkout',
   'output-schema',
   'diff-instructions',
   'file-level-guidance',

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

@@ -92,6 +92,10 @@ Focus on relationships between changed code and existing patterns.
 Do NOT modify files.
 </section>
 
+<section name="sparse-checkout" optional="true" tier="fast,balanced,thorough">
+{{sparseCheckoutGuidance}}
+</section>
+
 <section name="output-schema" locked="true">
 ## Output Format
 
@@ -155,6 +159,7 @@ const sections = [
   { name: 'analysis-process', required: true, tier: ['fast'] },
   { name: 'focus-areas', required: true, tier: ['fast'] },
   { name: 'available-commands', required: true, tier: ['fast'] },
+  { name: 'sparse-checkout', optional: true, tier: ['fast', 'balanced', 'thorough'] },
   { name: 'output-schema', locked: true },
   { name: 'diff-instructions', required: true, tier: ['fast'] },
   { name: 'guidelines', required: true, tier: ['fast'] }
@@ -176,6 +181,7 @@ const defaultOrder = [
   'analysis-process',
   'focus-areas',
   'available-commands',
+  'sparse-checkout',
   'output-schema',
   'diff-instructions',
   'guidelines'

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

@@ -40,7 +40,7 @@ const taggedPrompt = `<section name="role" required="true" tier="thorough">
 {{prContext}}
 </section>
 
-<section name="custom-instructions" optional="true" tier="balanced,thorough">
+<section name="custom-instructions" optional="true" tier="fast,balanced,thorough">
 {{customInstructions}}
 </section>
 
@@ -75,7 +75,7 @@ Approach this analysis systematically, building understanding from specific chan
 **Calibrate your output**: Quality matters more than speed. Surface fewer high-confidence findings that genuinely require codebase-wide understanding.
 </section>
 
-<section name="generated-files" optional="true" tier="balanced,thorough">
+<section name="generated-files" optional="true" tier="fast,balanced,thorough">
 {{generatedFiles}}
 </section>
 
@@ -234,6 +234,10 @@ Note: You may optionally use parallel read-only Tasks to explore different areas
 - Analyzing test coverage in parallel with main code analysis
 </section>
 
+<section name="sparse-checkout" optional="true" tier="fast,balanced,thorough">
+{{sparseCheckoutGuidance}}
+</section>
+
 <section name="output-schema" locked="true">
 ## Output Format
 
@@ -377,16 +381,17 @@ Level 3 findings must require codebase context. If an issue could be identified
 const sections = [
   { name: 'role', required: true, tier: ['thorough'] },
   { name: 'pr-context', locked: true },
-  { name: 'custom-instructions', optional: true, tier: ['balanced', 'thorough'] },
+  { name: 'custom-instructions', optional: true, tier: ['fast', 'balanced', 'thorough'] },
   { name: 'level-header', required: true, tier: ['thorough'] },
   { name: 'line-number-guidance', required: true, tier: ['thorough'] },
   { name: 'reasoning-encouragement', required: true, tier: ['thorough'] },
-  { name: 'generated-files', optional: true, tier: ['balanced', 'thorough'] },
+  { name: 'generated-files', optional: true, tier: ['fast', 'balanced', 'thorough'] },
   { name: 'changed-files', locked: true },
   { name: 'purpose', required: true, tier: ['thorough'] },
   { name: 'analysis-process', required: true, tier: ['thorough'] },
   { name: 'focus-areas', required: true, tier: ['thorough'] },
   { name: 'available-commands', required: true, tier: ['thorough'] },
+  { name: 'sparse-checkout', optional: true, tier: ['fast', 'balanced', 'thorough'] },
   { name: 'output-schema', locked: true },
   { name: 'diff-instructions', required: true, tier: ['thorough'] },
   { name: 'confidence-guidance', required: true, tier: ['thorough'] },
@@ -412,6 +417,7 @@ const defaultOrder = [
   'analysis-process',
   'focus-areas',
   'available-commands',
+  'sparse-checkout',
   'output-schema',
   'diff-instructions',
   'confidence-guidance',

package/src/ai/prompts/render-for-skill.js

@@ -13,6 +13,7 @@ const {
   buildAnalysisLineNumberGuidance,
   buildOrchestrationLineNumberGuidance,
 } = require('./line-number-guidance');
+const { buildSparseCheckoutGuidance } = require('./sparse-checkout-guidance');
 
 /**
  * Skill-appropriate default values for prompt placeholders.
@@ -49,6 +50,12 @@ const SKILL_DEFAULTS = {
   // Collapse when empty
   generatedFiles: '',
   customInstructions: '',
+
+  // For standalone skill usage, include conditional sparse-checkout guidance
+  // since we don't know if the review context uses sparse-checkout.
+  // The conditional flag produces softer language that doesn't assert
+  // sparse-checkout is active — only advises what to do if it is.
+  sparseCheckoutGuidance: buildSparseCheckoutGuidance({ conditional: true }),
 };
 
 /**

package/src/ai/prompts/sparse-checkout-guidance.js

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+/**
+ * Sparse-checkout guidance for analysis prompts.
+ * Injected when the worktree uses sparse-checkout.
+ */
+
+/**
+ * Build sparse-checkout guidance for analysis prompts.
+ *
+ * When called with `conditional: true` (the skill/standalone path),
+ * produces softer language that doesn't assert sparse-checkout is active
+ * — only advises what to do *if* it is.  The live Analyzer path omits
+ * this flag because it has already verified sparse-checkout is enabled.
+ *
+ * @param {Object} options
+ * @param {string[]} options.patterns - Current sparse-checkout patterns
+ * @param {boolean} [options.conditional=false] - Use conditional language
+ *   (for contexts where we don't know whether sparse-checkout is active)
+ * @returns {string} Markdown guidance
+ */
+function buildSparseCheckoutGuidance(options = {}) {
+  const { patterns = [], conditional = false } = options;
+
+  if (conditional) {
+    return buildConditionalGuidance();
+  }
+
+  const patternList = patterns.length > 0
+    ? patterns.map(p => `  - ${p}`).join('\n')
+    : '  (run `git sparse-checkout list` to see current patterns)';
+
+  return `
+## Sparse Checkout Active
+
+This repository uses sparse-checkout. Only a subset of directories are checked out:
+${patternList}
+
+**Exploring related code**: If you need to examine code outside the checked-out directories to understand dependencies, patterns, or impacts, you can expand the checkout:
+\`\`\`
+git sparse-checkout add <directory>
+\`\`\`
+
+For example, if you see an import from \`packages/shared-utils\` but that directory isn't checked out, run:
+\`\`\`
+git sparse-checkout add packages/shared-utils
+\`\`\`
+
+This is non-destructive and only adds to what's visible in this review worktree.
+`;
+}
+
+/**
+ * Build conditional sparse-checkout guidance for contexts where we cannot
+ * determine whether sparse-checkout is active (e.g., standalone skills
+ * that lack worktree access).
+ * @returns {string} Markdown guidance with conditional framing
+ */
+function buildConditionalGuidance() {
+  return `
+## Monorepo / Sparse Checkout Considerations
+
+If this repository uses sparse-checkout, only a subset of directories may be checked out. You can check by running:
+\`\`\`
+git sparse-checkout list
+\`\`\`
+
+If sparse-checkout is active and you need to examine code outside the checked-out directories to understand dependencies, patterns, or impacts, you can expand the checkout:
+\`\`\`
+git sparse-checkout add <directory>
+\`\`\`
+
+This is non-destructive and only adds to what's visible in the worktree.
+`;
+}
+
+module.exports = { buildSparseCheckoutGuidance };

package/src/config.js

@@ -19,7 +19,8 @@ const DEFAULT_CONFIG = {
   dev_mode: false,  // When true, disables static file caching for development
   debug_stream: false,  // When true, logs AI provider streaming events (equivalent to --debug-stream CLI flag)
   yolo: false,  // When true, skips fine-grained AI provider permission setup (equivalent to --yolo CLI flag)
-  providers: {}  // Custom provider configurations (overrides built-in defaults)
+  providers: {},  // Custom provider configurations (overrides built-in defaults)
+  monorepos: {}  // Monorepo configurations: { "owner/repo": { path: "~/path/to/clone" } }
 };
 
 /**
@@ -250,6 +251,40 @@ function showWelcomeMessage() {
 `);
 }
 
+/**
+ * Expands paths that start with ~/ to use the user's home directory.
+ *
+ * Note: Node.js does not have built-in tilde expansion. The os.homedir()
+ * function returns the home directory path but doesn't expand tildes in
+ * strings. This manual approach is the standard pattern; external packages
+ * like 'expand-tilde' exist but add unnecessary dependencies for this
+ * simple use case.
+ *
+ * @param {string} p - Path to expand
+ * @returns {string} - Expanded path
+ */
+function expandPath(p) {
+  if (!p) return p;
+  if (p.startsWith('~/')) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return p;
+}
+
+/**
+ * Gets the configured monorepo path for a repository
+ * @param {Object} config - Configuration object from loadConfig()
+ * @param {string} repository - Repository in "owner/repo" format
+ * @returns {string|null} - Expanded path or null if not configured
+ */
+function getMonorepoPath(config, repository) {
+  const monorepoConfig = config.monorepos?.[repository];
+  if (monorepoConfig?.path) {
+    return expandPath(monorepoConfig.path);
+  }
+  return null;
+}
+
 module.exports = {
   loadConfig,
   saveConfig,
@@ -259,5 +294,7 @@ module.exports = {
   getDefaultProvider,
   getDefaultModel,
   isRunningViaNpx,
-  showWelcomeMessage
+  showWelcomeMessage,
+  expandPath,
+  getMonorepoPath
 };

package/src/git/worktree.js

@@ -26,10 +26,14 @@ class GitWorktreeManager {
    * Create a git worktree for a PR and checkout to the PR head commit
    * @param {Object} prInfo - PR information { owner, repo, number }
    * @param {Object} prData - PR data from GitHub API
-   * @param {string} repositoryPath - Local repository path
+   * @param {string} repositoryPath - Local repository path (main git root)
+   * @param {Object} [options] - Optional settings
+   * @param {string} [options.worktreeSourcePath] - Path to use as cwd for git worktree add
+   *   (to inherit sparse-checkout from an existing worktree). Falls back to repositoryPath.
    * @returns {Promise<string>} Path to created worktree
    */
-  async createWorktreeForPR(prInfo, prData, repositoryPath) {
+  async createWorktreeForPR(prInfo, prData, repositoryPath, options = {}) {
+    const { worktreeSourcePath } = options;
     // Check if worktree already exists in DB
     const repository = normalizeRepository(prInfo.owner, prInfo.repo);
     let worktreePath;
@@ -130,14 +134,20 @@ class GitWorktreeManager {
       }
       
       // Create worktree and checkout to base branch
-      console.log(`Creating worktree at ${worktreePath} from ${prData.base_branch}...`);
+      // Use worktreeSourcePath as cwd if provided (to inherit sparse-checkout from existing worktree)
+      const worktreeAddGit = worktreeSourcePath ? simpleGit(worktreeSourcePath) : git;
+      if (worktreeSourcePath) {
+        console.log(`Creating worktree at ${worktreePath} from ${prData.base_branch} (inheriting sparse-checkout from ${worktreeSourcePath})...`);
+      } else {
+        console.log(`Creating worktree at ${worktreePath} from ${prData.base_branch}...`);
+      }
       try {
-        await git.raw(['worktree', 'add', worktreePath, `origin/${prData.base_branch}`]);
+        await worktreeAddGit.raw(['worktree', 'add', worktreePath, `origin/${prData.base_branch}`]);
       } catch (worktreeError) {
         // If worktree creation fails due to existing registration, try with --force
         if (worktreeError.message.includes('already registered')) {
           console.log('Worktree already registered, trying with --force...');
-          await git.raw(['worktree', 'add', '--force', worktreePath, `origin/${prData.base_branch}`]);
+          await worktreeAddGit.raw(['worktree', 'add', '--force', worktreePath, `origin/${prData.base_branch}`]);
         } else {
           throw worktreeError;
         }
@@ -692,6 +702,98 @@ class GitWorktreeManager {
       };
     }
   }
+
+  /**
+   * Check if sparse-checkout is enabled for a git repository
+   * @param {string} repoPath - Path to the git repository or worktree
+   * @returns {Promise<boolean>} Whether sparse-checkout is enabled
+   */
+  async isSparseCheckoutEnabled(repoPath) {
+    try {
+      const git = simpleGit(repoPath);
+      const config = await git.raw(['config', 'core.sparseCheckout']);
+      return config.trim() === 'true';
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get current sparse-checkout patterns
+   * @param {string} repoPath - Path to the git repository or worktree
+   * @returns {Promise<string[]>} Array of sparse-checkout patterns
+   */
+  async getSparseCheckoutPatterns(repoPath) {
+    try {
+      const git = simpleGit(repoPath);
+      const output = await git.raw(['sparse-checkout', 'list']);
+      return output.trim().split('\n').filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Ensure all directories containing changed files are in sparse-checkout.
+   * Finds the minimal set of directories to add.
+   *
+   * @param {string} worktreePath - Path to the worktree
+   * @param {Array} changedFiles - Array of changed file objects with filename or file property
+   * @returns {Promise<string[]>} Directories that were added
+   */
+  async ensurePRDirectoriesInSparseCheckout(worktreePath, changedFiles) {
+    if (!await this.isSparseCheckoutEnabled(worktreePath)) {
+      return [];
+    }
+
+    const currentPatterns = await this.getSparseCheckoutPatterns(worktreePath);
+
+    // Extract unique directory paths from changed files
+    // Support both {filename} and {file} properties
+    const neededDirs = new Set();
+    for (const file of changedFiles) {
+      const filename = file.filename || file.file;
+      if (!filename) continue;
+      // Add only the immediate parent directory of the file.
+      // Root-level files (no '/') are skipped — cone mode always includes the repo root.
+      const lastSlash = filename.lastIndexOf('/');
+      if (lastSlash > 0) {
+        neededDirs.add(filename.substring(0, lastSlash));
+      }
+    }
+
+    // Find directories not covered by current patterns.
+    // NOTE: This uses startsWith() for directory-based comparison, which only
+    // supports cone mode (directory path patterns). Glob-based sparse-checkout
+    // patterns (e.g., '*.js', '**/test/') would not be matched correctly.
+    // This is acceptable for now since we only support cone mode throughout
+    // the worktree implementation. See tech debt tracking for glob support.
+    const missingDirs = [...neededDirs].filter(dir => {
+      // Check if dir is already covered by an existing pattern
+      return !currentPatterns.some(pattern => {
+        // Covered if: exact match or dir is inside pattern (pattern is parent).
+        // Note: we do NOT check pattern.startsWith(dir + '/') because a child
+        // pattern (e.g., 'packages/core') does not cover files directly under
+        // the parent directory (e.g., 'packages/package.json').
+        return dir === pattern ||
+               dir.startsWith(pattern + '/');
+      });
+    });
+
+    // Find minimal set (remove dirs whose parents are also in missingDirs)
+    const minimalDirs = missingDirs.filter(dir => {
+      return !missingDirs.some(other =>
+        other !== dir && dir.startsWith(other + '/')
+      );
+    });
+
+    if (minimalDirs.length > 0) {
+      const git = simpleGit(worktreePath);
+      await git.raw(['sparse-checkout', 'add', ...minimalDirs]);
+    }
+
+    return minimalDirs;
+  }
 }
 
 module.exports = { GitWorktreeManager };

package/src/github/client.js

@@ -83,6 +83,41 @@ class GitHubClient {
     }
   }
 
+  /**
+   * Fetch the list of files changed in a pull request.
+   *
+   * Uses the GitHub REST API `pulls.listFiles` endpoint, which returns an
+   * array of file objects (with `filename`, `status`, `additions`, etc.).
+   * This is distinct from the `changed_files` integer returned by
+   * `pulls.get`, which is only a count.
+   *
+   * Paginates automatically to handle PRs with more than 100 changed files.
+   *
+   * @param {string} owner - Repository owner
+   * @param {string} repo - Repository name
+   * @param {number} pullNumber - Pull request number
+   * @returns {Promise<Array<{filename: string, status: string, additions: number, deletions: number, changes: number}>>}
+   */
+  async fetchPullRequestFiles(owner, repo, pullNumber) {
+    try {
+      const files = await this.octokit.paginate(this.octokit.rest.pulls.listFiles, {
+        owner,
+        repo,
+        pull_number: pullNumber,
+        per_page: 100
+      });
+      return files.map(f => ({
+        filename: f.filename,
+        status: f.status,
+        additions: f.additions,
+        deletions: f.deletions,
+        changes: f.changes
+      }));
+    } catch (error) {
+      await this.handleApiError(error, owner, repo, pullNumber);
+    }
+  }
+
   /**
    * Validate GitHub token by making a test API call
    * @returns {Promise<boolean>} Whether the token is valid

package/src/github/parser.js

@@ -218,6 +218,62 @@ class PRArgumentParser {
     return process.cwd();
   }
 
+  /**
+   * Check if a directory is a git repository that matches the specified owner/repo.
+   * Compares the git remote origin URL against the expected owner/repo.
+   *
+   * @param {string} directory - Directory path to check
+   * @param {string} expectedOwner - Expected repository owner
+   * @param {string} expectedRepo - Expected repository name
+   * @returns {Promise<boolean>} True if the directory is a matching git repository
+   */
+  async isMatchingRepository(directory, expectedOwner, expectedRepo) {
+    try {
+      // Use _createGitForDirectory for testability (can be overridden in tests)
+      const git = this._createGitForDirectory(directory);
+
+      // Check if it's a git repository
+      const isRepo = await git.checkIsRepo();
+      if (!isRepo) {
+        return false;
+      }
+
+      // Get remote origin URL
+      const remotes = await git.getRemotes(true);
+      const origin = remotes.find(remote => remote.name === 'origin');
+
+      if (!origin) {
+        return false;
+      }
+
+      const remoteUrl = origin.refs.fetch || origin.refs.push;
+      if (!remoteUrl) {
+        return false;
+      }
+
+      // Parse the owner/repo from the remote URL
+      const { owner, repo } = this.parseRepositoryFromURL(remoteUrl);
+
+      // Compare case-insensitively (GitHub repos are case-insensitive)
+      return owner.toLowerCase() === expectedOwner.toLowerCase() &&
+             repo.toLowerCase() === expectedRepo.toLowerCase();
+    } catch (error) {
+      // Any error means the directory doesn't match
+      return false;
+    }
+  }
+
+  /**
+   * Create a git instance for a given directory.
+   * This method exists for testability - tests can override it.
+   * @param {string} directory - Directory path
+   * @returns {Object} simpleGit instance
+   * @private
+   */
+  _createGitForDirectory(directory) {
+    return simpleGit(directory);
+  }
+
   /**
    * Check if current directory is a git repository
    * @returns {Promise<boolean>} Whether current directory is a git repo

package/src/local-review.js

@@ -57,11 +57,20 @@ async function findMainGitRoot(repoPath) {
 
     // For worktrees, commonDir is an absolute path like "/path/to/main/.git"
     // or a relative path like "../main/.git"
-    // Resolve it and go up one level to get the main repo root
     const resolvedCommonDir = path.resolve(repoPath, commonDir);
-    const mainRepoRoot = path.dirname(resolvedCommonDir);
 
-    return mainRepoRoot;
+    // Determine if this is a .git directory (regular repo) or a bare repo
+    // Regular repos: commonDir ends with ".git" (e.g., /path/to/repo/.git)
+    // Bare repos: commonDir is the repo itself (e.g., /path/to/repo.git or /path/to/git)
+    // The key difference: for regular repos, basename is exactly ".git"
+    const basename = path.basename(resolvedCommonDir);
+    if (basename === '.git') {
+      // Regular repo - go up one level to get the repo root
+      return path.dirname(resolvedCommonDir);
+    } else {
+      // Bare repo - the commonDir IS the repo
+      return resolvedCommonDir;
+    }
   } catch (error) {
     throw new Error(`Failed to find main git root: ${error.message}`);
   }

package/src/main.js

@@ -9,7 +9,7 @@ const { startServer } = require('./server');
 const Analyzer = require('./ai/analyzer');
 const { applyConfigOverrides } = require('./ai');
 const { handleLocalReview, findMainGitRoot } = require('./local-review');
-const { storePRData, registerRepositoryLocation } = require('./setup/pr-setup');
+const { storePRData, registerRepositoryLocation, findRepositoryPath } = require('./setup/pr-setup');
 const { normalizeRepository, resolveRenamedFile, resolveRenamedFileOld } = require('./utils/paths');
 const logger = require('./utils/logger');
 const simpleGit = require('simple-git');
@@ -484,16 +484,39 @@ async function handlePullRequest(args, config, db, flags = {}) {
     console.log('Fetching pull request data from GitHub...');
     const prData = await githubClient.fetchPullRequest(prInfo.owner, prInfo.repo, prInfo.number);
 
-    // Get current repository path
+    // Determine repository path: only use cwd if it matches the target repo
     const currentDir = parser.getCurrentDirectory();
+    const isMatchingRepo = await parser.isMatchingRepository(currentDir, prInfo.owner, prInfo.repo);
 
-    // Register the known repository location for future web UI usage
-    await registerRepositoryLocation(db, currentDir, prInfo.owner, prInfo.repo);
+    let repositoryPath;
+    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);
+    } 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 repository = normalizeRepository(prInfo.owner, prInfo.repo);
+      const result = await findRepositoryPath({
+        db,
+        owner: prInfo.owner,
+        repo: prInfo.repo,
+        repository,
+        prNumber: prInfo.number,
+        onProgress: (progress) => {
+          if (progress.message) {
+            console.log(progress.message);
+          }
+        }
+      });
+      repositoryPath = result.repositoryPath;
+    }
 
     // Setup git worktree
     console.log('Setting up git worktree...');
     const worktreeManager = new GitWorktreeManager(db);
-    const worktreePath = await worktreeManager.createWorktreeForPR(prInfo, prData, currentDir);
+    const worktreePath = await worktreeManager.createWorktreeForPR(prInfo, prData, repositoryPath);
 
     // Generate unified diff
     console.log('Generating unified diff...');
@@ -701,7 +724,6 @@ async function performHeadlessReview(args, config, db, flags, options) {
     console.log('Fetching pull request data from GitHub...');
     const prData = await githubClient.fetchPullRequest(prInfo.owner, prInfo.repo, prInfo.number);
 
-    const repository = normalizeRepository(prInfo.owner, prInfo.repo);
     let worktreePath;
     let diff;
     let changedFiles;
@@ -709,6 +731,16 @@ async function performHeadlessReview(args, config, db, flags, options) {
     // Determine working directory: --use-checkout uses current directory
     if (flags.useCheckout) {
       worktreePath = process.cwd();
+
+      // Verify cwd matches the target repository when using --use-checkout
+      const isMatchingRepo = await parser.isMatchingRepository(worktreePath, prInfo.owner, prInfo.repo);
+      if (!isMatchingRepo) {
+        throw new Error(
+          `--use-checkout requires running from a checkout of ${prInfo.owner}/${prInfo.repo}, ` +
+          `but current directory does not match. Either cd to the correct repository or remove --use-checkout.`
+        );
+      }
+
       await registerRepositoryLocation(db, worktreePath, prInfo.owner, prInfo.repo);
       console.log(`Using current checkout at ${worktreePath}`);
 
@@ -752,13 +784,37 @@ async function performHeadlessReview(args, config, db, flags, options) {
         return result;
       });
     } else {
-      // Use worktree approach
+      // Use worktree approach - only use cwd if it matches the target repo
       const currentDir = parser.getCurrentDirectory();
-      await registerRepositoryLocation(db, currentDir, prInfo.owner, prInfo.repo);
+      const isMatchingRepo = await parser.isMatchingRepository(currentDir, prInfo.owner, prInfo.repo);
+
+      let repositoryPath;
+      if (isMatchingRepo) {
+        // Current directory is a checkout of the target repository
+        repositoryPath = currentDir;
+        await registerRepositoryLocation(db, currentDir, prInfo.owner, prInfo.repo);
+      } 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 repository = normalizeRepository(prInfo.owner, prInfo.repo);
+        const result = await findRepositoryPath({
+          db,
+          owner: prInfo.owner,
+          repo: prInfo.repo,
+          repository,
+          prNumber: prInfo.number,
+          onProgress: (progress) => {
+            if (progress.message) {
+              console.log(progress.message);
+            }
+          }
+        });
+        repositoryPath = result.repositoryPath;
+      }
 
       console.log('Setting up git worktree...');
       const worktreeManager = new GitWorktreeManager(db);
-      worktreePath = await worktreeManager.createWorktreeForPR(prInfo, prData, currentDir);
+      worktreePath = await worktreeManager.createWorktreeForPR(prInfo, prData, repositoryPath);
 
       console.log('Generating unified diff...');
       diff = await worktreeManager.generateUnifiedDiff(worktreePath, prData);

package/src/routes/setup.js

@@ -113,6 +113,7 @@ router.post('/api/setup/pr/:owner/:repo/:number', async (req, res) => {
           repo,
           prNumber,
           githubToken,
+          config,
           onProgress: (progress) => {
             sendSetupSSE(setupId, 'step', progress);
           }

package/src/routes/worktrees.js

@@ -62,6 +62,7 @@ router.post('/api/worktrees/create', async (req, res) => {
       repo,
       prNumber: parsedPrNumber,
       githubToken,
+      config,
       onProgress: (progress) => {
         logger.info(`[Setup] ${progress.step}: ${progress.message}`);
       }

package/src/setup/pr-setup.js

@@ -16,7 +16,7 @@ const { GitWorktreeManager } = require('../git/worktree');
 const { GitHubClient } = require('../github/client');
 const { normalizeRepository } = require('../utils/paths');
 const { findMainGitRoot } = require('../local-review');
-const { getConfigDir } = require('../config');
+const { getConfigDir, getMonorepoPath } = require('../config');
 const logger = require('../utils/logger');
 const simpleGit = require('simple-git');
 const fs = require('fs').promises;
@@ -188,6 +188,7 @@ async function registerRepositoryLocation(db, currentDir, owner, repo) {
  * given owner/repo so that worktrees can be created from it.
  *
  * Tiers (in order of preference):
+ *  -1. Explicit monorepo configuration (highest priority)
  *   0. Known local path from repo_settings (registered by CLI or previous web UI)
  *   1. Existing worktree for this repo (derive parent git root from it)
  *   2. Cached clone at <configDir>/repos/<owner>/<repo>
@@ -199,25 +200,83 @@ async function registerRepositoryLocation(db, currentDir, owner, repo) {
  * @param {string} params.repo - Repository name
  * @param {string} params.repository - Normalized "owner/repo" string
  * @param {number} params.prNumber - PR number (used for worktree lookup)
+ * @param {Object} [params.config] - Application config (used for monorepo path lookup)
  * @param {Function} [params.onProgress] - Optional progress callback
- * @returns {Promise<{ repositoryPath: string, knownPath: string|null }>}
+ * @returns {Promise<{ repositoryPath: string, knownPath: string|null, worktreeSourcePath: string|null }>}
+ *   - repositoryPath: the main git root (bare repo or .git parent)
+ *   - knownPath: the known path from database (if any)
+ *   - worktreeSourcePath: path to use as cwd for `git worktree add` (may be a worktree with sparse-checkout)
  */
-async function findRepositoryPath({ db, owner, repo, repository, prNumber, onProgress }) {
+async function findRepositoryPath({ db, owner, repo, repository, prNumber, config, onProgress }) {
   const worktreeManager = new GitWorktreeManager(db);
   const repoSettingsRepo = new RepoSettingsRepository(db);
   const worktreeRepo = new WorktreeRepository(db);
 
   let repositoryPath = null;
+  let worktreeSourcePath = null;  // Path to use as cwd for `git worktree add` (may differ from repositoryPath)
+
+  // ------------------------------------------------------------------
+  // Tier -1: Explicit monorepo configuration (highest priority)
+  // ------------------------------------------------------------------
+  const monorepoPath = config ? getMonorepoPath(config, repository) : null;
+
+  if (monorepoPath) {
+    // The configured path might be a worktree or a regular/bare repo.
+    // We need the main git root for creating new worktrees, but we also want to
+    // preserve the original path if it's a worktree so sparse-checkout is inherited.
+    // Wrap in try-catch since findMainGitRoot throws if path doesn't exist or isn't a git repo
+    try {
+      const resolvedPath = await findMainGitRoot(monorepoPath);
+      logger.debug(`Monorepo path ${monorepoPath} resolved to ${resolvedPath}`);
+
+      // Check if this is a valid git directory we can create worktrees from.
+      // It could be:
+      // 1. A regular repo (has .git directory)
+      // 2. A bare repo (is itself a git directory with HEAD, objects, refs)
+      // 3. A worktree (has .git file pointing to actual git dir)
+      const gitDirPath = path.join(resolvedPath, '.git');
+      const headPath = path.join(resolvedPath, 'HEAD');
+
+      const hasGitDir = await worktreeManager.pathExists(gitDirPath);
+      const hasHead = await worktreeManager.pathExists(headPath);
+
+      if (hasGitDir || hasHead) {
+        // Verify we can actually run git commands here
+        try {
+          const git = simpleGit(resolvedPath);
+          await git.revparse(['HEAD']);
+          repositoryPath = resolvedPath;
+
+          // If the configured path differs from the resolved path, it's likely a worktree.
+          // Use the original configured path as the source for worktree creation so
+          // sparse-checkout configuration is inherited.
+          if (monorepoPath !== resolvedPath) {
+            worktreeSourcePath = monorepoPath;
+            logger.info(`Using configured monorepo path at ${repositoryPath} (worktree source: ${worktreeSourcePath})`);
+          } else {
+            logger.info(`Using configured monorepo path at ${repositoryPath}`);
+          }
+        } catch (gitError) {
+          logger.warn(`Configured monorepo path ${monorepoPath} resolved to ${resolvedPath} but git commands fail: ${gitError.message}`);
+        }
+      } else {
+        logger.warn(`Configured monorepo path ${monorepoPath} resolved to ${resolvedPath} which has no .git directory or HEAD file`);
+      }
+    } catch (resolveError) {
+      logger.warn(`Configured monorepo path ${monorepoPath} does not exist or is not a git repository: ${resolveError.message}`);
+    }
+  }
 
   // ------------------------------------------------------------------
   // Tier 0: Check known local path from repo_settings
   // ------------------------------------------------------------------
   const knownPath = await repoSettingsRepo.getLocalPath(repository);
 
-  if (knownPath && await worktreeManager.pathExists(knownPath)) {
+  if (!repositoryPath && knownPath && await worktreeManager.pathExists(knownPath)) {
     try {
       const git = simpleGit(knownPath);
-      await git.revparse(['--is-inside-work-tree']);
+      // Use --git-dir instead of --is-inside-work-tree to support bare repos
+      await git.revparse(['--git-dir']);
       repositoryPath = knownPath;
       logger.info(`Using known repository location at ${repositoryPath}`);
     } catch {
@@ -276,7 +335,7 @@ async function findRepositoryPath({ db, owner, repo, repository, prNumber, onPro
     }
   }
 
-  return { repositoryPath, knownPath };
+  return { repositoryPath, knownPath, worktreeSourcePath };
 }
 
 /**
@@ -292,10 +351,11 @@ async function findRepositoryPath({ db, owner, repo, repository, prNumber, onPro
  * @param {string} params.repo - Repository name
  * @param {number} params.prNumber - Pull request number
  * @param {string} params.githubToken - GitHub PAT
+ * @param {Object} [params.config] - Application config (for monorepo path lookup)
  * @param {Function} [params.onProgress] - Optional progress callback
  * @returns {Promise<{ reviewUrl: string, title: string }>}
  */
-async function setupPRReview({ db, owner, repo, prNumber, githubToken, onProgress }) {
+async function setupPRReview({ db, owner, repo, prNumber, githubToken, config, onProgress }) {
   const repository = normalizeRepository(owner, repo);
   const progress = onProgress || (() => {});
 
@@ -321,12 +381,13 @@ async function setupPRReview({ db, owner, repo, prNumber, githubToken, onProgres
   // Step: repo - Find (or clone) a local repository
   // ------------------------------------------------------------------
   progress({ step: 'repo', status: 'running', message: 'Locating repository...' });
-  const { repositoryPath, knownPath } = await findRepositoryPath({
+  const { repositoryPath, knownPath, worktreeSourcePath } = await findRepositoryPath({
     db,
     owner,
     repo,
     repository,
     prNumber,
+    config,
     onProgress: progress
   });
   progress({ step: 'repo', status: 'completed', message: `Repository located at ${repositoryPath}` });
@@ -337,9 +398,41 @@ async function setupPRReview({ db, owner, repo, prNumber, githubToken, onProgres
   progress({ step: 'worktree', status: 'running', message: 'Setting up git worktree...' });
   const worktreeManager = new GitWorktreeManager(db);
   const prInfo = { owner, repo, number: prNumber };
-  const worktreePath = await worktreeManager.createWorktreeForPR(prInfo, prData, repositoryPath);
+  // Use worktreeSourcePath as cwd for git worktree add (if available) to inherit sparse-checkout
+  const worktreePath = await worktreeManager.createWorktreeForPR(prInfo, prData, repositoryPath, { worktreeSourcePath });
   progress({ step: 'worktree', status: 'completed', message: `Worktree created at ${worktreePath}` });
 
+  // ------------------------------------------------------------------
+  // Step: sparse - Expand sparse-checkout before generating diff
+  // ------------------------------------------------------------------
+  // IMPORTANT: Sparse-checkout expansion MUST happen before diff generation.
+  // In monorepo worktrees that inherit a sparse-checkout from the source
+  // worktree, the checkout may not include all directories touched by the PR.
+  // If we generate the diff first, files outside the sparse cone will be missing
+  // from the worktree, producing an incomplete or empty diff. Expanding the
+  // sparse-checkout ensures every PR-changed directory is present on disk so
+  // that `git diff` can read the actual file contents.
+  //
+  // NOTE: prData.changed_files is an INTEGER (count) from the GitHub pulls.get
+  // API, not an array. We must fetch the actual file list via pulls.listFiles.
+  if (prData.changed_files > 0) {
+    const isSparse = await worktreeManager.isSparseCheckoutEnabled(worktreePath);
+    if (isSparse) {
+      progress({ step: 'sparse', status: 'running', message: 'Expanding sparse-checkout for PR directories...' });
+      try {
+        const prFiles = await githubClient.fetchPullRequestFiles(owner, repo, prNumber);
+        const addedDirs = await worktreeManager.ensurePRDirectoriesInSparseCheckout(worktreePath, prFiles);
+        if (addedDirs.length > 0) {
+          logger.info(`Expanded sparse-checkout for PR directories: ${addedDirs.join(', ')}`);
+        }
+        progress({ step: 'sparse', status: 'completed', message: addedDirs.length > 0 ? `Expanded: ${addedDirs.join(', ')}` : 'No expansion needed' });
+      } catch (sparseError) {
+        logger.warn(`Sparse-checkout expansion failed (non-fatal): ${sparseError.message}`);
+        progress({ step: 'sparse', status: 'completed', message: `Sparse-checkout expansion skipped: ${sparseError.message}` });
+      }
+    }
+  }
+
   // ------------------------------------------------------------------
   // Step: diff - Generate unified diff and changed file list
   // ------------------------------------------------------------------