feat: add --local mode for reviewing local git diffs

Support reviewing local git diffs without requiring a PR URL.
Useful for Bitbucket PRs or pre-push local reviews.

Usage:
  hodor --local                          # diff against origin/main
  hodor --local --diff-against HEAD~1    # diff against specific ref

In local mode:
- Uses current directory (or --workspace) as workspace
- Skips PR metadata fetching and workspace cloning
- --post is disabled (no remote to post to)
- Diff embedding and compaction work as normal

Closes #8

Author: mr-karan

src/agent.ts

@@ -167,7 +167,7 @@ export async function postReviewComment(opts: {
 }
 
 export async function reviewPr(opts: {
-  prUrl: string;
+  prUrl?: string;
   model?: string;
   reasoningEffort?: string;
   customPrompt?: string | null;
@@ -177,6 +177,8 @@ export async function reviewPr(opts: {
   includeMetricsFooter?: boolean;
   onEvent?: (event: AgentProgressEvent) => void;
   bedrockTags?: Record<string, string> | null;
+  localMode?: boolean;
+  diffAgainst?: string;
 }): Promise<{ review: ReviewOutput; metricsFooter: string | null; headSha: string | null; metrics: ReviewMetrics }> {
   const {
     prUrl,
@@ -189,14 +191,25 @@ export async function reviewPr(opts: {
     includeMetricsFooter = false,
     onEvent,
     bedrockTags,
+    localMode = false,
+    diffAgainst,
   } = opts;
 
-  logger.info(`Starting PR review for: ${prUrl}`);
+  logger.info(`Starting PR review for: ${localMode ? "local diff" : prUrl}`);
 
-  // Parse PR URL
-  const { owner, repo, prNumber, host } = parsePrUrl(prUrl);
-  const platform = detectPlatform(prUrl);
-  logger.info(`Platform: ${platform}, Repo: ${owner}/${repo}, PR: ${prNumber}, Host: ${host}`);
+  let owner = "", repo = "", host = "";
+  let prNumber = 0;
+  let platform: Platform = "github";
+
+  if (!localMode && prUrl) {
+    const urlParsed = parsePrUrl(prUrl);
+    owner = urlParsed.owner;
+    repo = urlParsed.repo;
+    prNumber = urlParsed.prNumber;
+    host = urlParsed.host;
+    platform = detectPlatform(prUrl);
+    logger.info(`Platform: ${platform}, Repo: ${owner}/${repo}, PR: ${prNumber}, Host: ${host}`);
+  }
 
   // --- Preflight: validate model + credentials before any expensive I/O ---
   const parsed = parseModelString(model);
@@ -285,30 +298,49 @@ export async function reviewPr(opts: {
   // --- End preflight ---
 
   // Setup workspace
-  const { workspace, targetBranch, diffBaseSha, isTemporary } = await setupWorkspace({
-    platform,
-    owner,
-    repo,
-    prNumber: String(prNumber),
-    host,
-    workingDir: workspaceDir ?? undefined,
-    reuse: workspaceDir != null,
-  });
-
-  const workspacePath = workspace;
+  let workspacePath: string;
+  let targetBranch: string;
+  let diffBaseSha: string | null = null;
+  let isTemporary = false;
+
+  if (localMode) {
+    // Resolve to git repo root so paths from git diff match tool expectations
+    const cwd = workspaceDir ?? process.cwd();
+    try {
+      const { stdout: toplevel } = await exec("git", ["rev-parse", "--show-toplevel"], { cwd });
+      workspacePath = toplevel.trim();
+    } catch {
+      workspacePath = cwd; // fallback if not in a git repo
+    }
+    targetBranch = diffAgainst ?? "origin/main";
+    logger.info(`Local mode: workspace=${workspacePath}, diffAgainst=${targetBranch}`);
+  } else {
+    const wsResult = await setupWorkspace({
+      platform,
+      owner,
+      repo,
+      prNumber: String(prNumber),
+      host,
+      workingDir: workspaceDir ?? undefined,
+      reuse: workspaceDir != null,
+    });
+    workspacePath = wsResult.workspace;
+    targetBranch = wsResult.targetBranch;
+    diffBaseSha = wsResult.diffBaseSha;
+    isTemporary = wsResult.isTemporary;
+  }
 
   try {
-    // Fetch PR metadata
     let mrMetadata: MrMetadata | null = null;
-    if (platform === "gitlab") {
+    if (!localMode && platform === "gitlab") {
       try {
         mrMetadata = await fetchGitlabMrInfo(owner, repo, prNumber, host, {
           includeComments: true,
         });
       } catch (err) {
         logger.warn(`Failed to fetch GitLab metadata: ${err}`);
       }
-    } else if (platform === "github") {
+    } else if (!localMode && platform === "github") {
       try {
         const githubRaw = await fetchGithubPrInfo(owner, repo, prNumber);
         mrMetadata = normalizeGithubMetadata(githubRaw);
@@ -340,9 +372,12 @@ export async function reviewPr(opts: {
       }
     }
 
-    // Get HEAD SHA for embedding in posted comments
-    const { stdout: headShaRaw } = await exec("git", ["rev-parse", "HEAD"], { cwd: workspacePath });
-    const headSha = headShaRaw.trim();
+    // Get HEAD SHA for embedding in posted comments (skip in local mode — no posting)
+    let headSha: string | null = null;
+    if (!localMode) {
+      const { stdout: headShaRaw } = await exec("git", ["rev-parse", "HEAD"], { cwd: workspacePath });
+      headSha = headShaRaw.trim();
+    }
 
     // Pre-fetch diff for embedding in prompt (avoids per-file tool calls)
     const MAX_EMBED_BYTES = 200 * 1024; // 200KB
@@ -352,7 +387,9 @@ export async function reviewPr(opts: {
         ? ["--no-pager", "diff", `${previousReviewSha}...HEAD`]
         : diffBaseSha
           ? ["--no-pager", "diff", diffBaseSha, "HEAD"]
-          : ["--no-pager", "diff", `origin/${targetBranch}...HEAD`];
+          : localMode
+            ? ["--no-pager", "diff", targetBranch]  // includes uncommitted changes
+            : ["--no-pager", "diff", `origin/${targetBranch}...HEAD`];
       const { stdout: rawDiff } = await exec("git", diffArgs, { cwd: workspacePath });
       if (Buffer.byteLength(rawDiff, "utf-8") <= MAX_EMBED_BYTES) {
         embeddedDiff = rawDiff;
@@ -366,7 +403,7 @@ export async function reviewPr(opts: {
 
     // Build prompt (always uses JSON template; rendered to markdown post-hoc)
     const prompt = buildPrReviewPrompt({
-      prUrl,
+      prUrl: prUrl ?? `local diff (against ${targetBranch})`,
       platform,
       targetBranch,
       diffBaseSha,
@@ -375,6 +412,7 @@ export async function reviewPr(opts: {
       customPromptFile: promptFile,
       embeddedDiff,
       previousReviewSha,
+      localMode,
     });
 
     const startTime = Date.now();

src/cli.ts

@@ -15,12 +15,13 @@ const program = new Command();
 program
   .name("hodor")
   .description(
-    "AI-powered code review agent for GitHub PRs and GitLab MRs.\n\n" +
+    "AI-powered code review agent for GitHub PRs, GitLab MRs, and local diffs.\n\n" +
       "Hodor uses an AI agent that clones the repository, checks out the PR branch,\n" +
-      "and analyzes the code using tools (gh, git, glab) for metadata fetching and comment posting.",
+      "and analyzes the code using tools (gh, git, glab) for metadata fetching and comment posting.\n\n" +
+      "For local reviews, use --local with --diff-against to review changes in your current git repository.",
   )
-  .version("0.3.4")
-  .argument("<pr-url>", "URL of the GitHub PR or GitLab MR to review")
+  .version("0.4.1")
+  .argument("[pr-url]", "URL of the GitHub PR or GitLab MR to review (optional with --local)")
   .option(
     "--model <model>",
     "LLM model to use (e.g., anthropic/claude-sonnet-4-5-20250929, openai/gpt-5)",
@@ -58,7 +59,17 @@ program
     "--prometheus-push <url>",
     "Push review metrics to a Prometheus Pushgateway URL",
   )
-  .action(async (prUrl: string, cmdOpts: Record<string, unknown>) => {
+  .option(
+    "--local",
+    "Review local changes in the current directory (no PR URL required)",
+    false,
+  )
+  .option(
+    "--diff-against <ref>",
+    "Git ref to diff against in local mode (e.g., origin/main, HEAD~1)",
+    "origin/main",
+  )
+  .action(async (prUrl: string | undefined, cmdOpts: Record<string, unknown>) => {
     const verbose = cmdOpts.verbose as boolean;
     const post = cmdOpts.post as boolean;
     const model = cmdOpts.model as string;
@@ -69,6 +80,17 @@ program
     const ultrathink = cmdOpts.ultrathink as boolean;
     const bedrockTagsRaw = cmdOpts.bedrockTags as string | undefined;
     const prometheusPush = cmdOpts.prometheusPush as string | undefined;
+    const localMode = cmdOpts.local as boolean;
+    const diffAgainst = cmdOpts.diffAgainst as string;
+
+    if (!localMode && !prUrl) {
+      console.error(chalk.red("Error: pr-url is required unless --local is specified"));
+      process.exit(1);
+    }
+    if (localMode && post) {
+      console.error(chalk.red("Error: --post is not supported in --local mode (no remote to post to)"));
+      process.exit(1);
+    }
 
     // Auto-detect CI environment
     const isCI = !!(process.env.CI || process.env.GITLAB_CI || process.env.GITHUB_ACTIONS);
@@ -168,41 +190,34 @@ program
     }
 
     try {
-      // Validate URL and detect platform (inside try so errors are caught)
-      const platform = detectPlatform(prUrl);
-      const githubToken = process.env.GITHUB_TOKEN;
-      const gitlabToken =
-        process.env.GITLAB_TOKEN ??
-        process.env.GITLAB_PRIVATE_TOKEN ??
-        process.env.CI_JOB_TOKEN;
+      // Detect platform and warn about missing tokens
+      let platform: string = "local";
+      if (!localMode && prUrl) {
+        platform = detectPlatform(prUrl);
+        const githubToken = process.env.GITHUB_TOKEN;
+        const gitlabToken =
+          process.env.GITLAB_TOKEN ??
+          process.env.GITLAB_PRIVATE_TOKEN ??
+          process.env.CI_JOB_TOKEN;
 
-      if (platform === "github" && !githubToken) {
-        console.error(
-          chalk.yellow(
-            "Warning: GITHUB_TOKEN not set. You may encounter rate limits or authentication issues.",
-          ),
-        );
-        console.error(
-          chalk.dim("  Set GITHUB_TOKEN environment variable or run: gh auth login\n"),
-        );
-      } else if (platform === "gitlab" && !gitlabToken) {
-        console.error(
-          chalk.yellow(
-            "Warning: No GitLab token detected. Set GITLAB_TOKEN (api scope) for authentication.",
-          ),
-        );
-        console.error(
-          chalk.dim(
-            "  Export GITLAB_TOKEN and optionally GITLAB_HOST for self-hosted instances.\n",
-          ),
-        );
+        if (platform === "github" && !githubToken) {
+          console.error(chalk.yellow("Warning: GITHUB_TOKEN not set. You may encounter rate limits."));
+          console.error(chalk.dim("  Set GITHUB_TOKEN or run: gh auth login\n"));
+        } else if (platform === "gitlab" && !gitlabToken) {
+          console.error(chalk.yellow("Warning: No GitLab token detected. Set GITLAB_TOKEN (api scope)."));
+          console.error(chalk.dim("  Export GITLAB_TOKEN and optionally GITLAB_HOST.\n"));
+        }
       }
 
-      log(
-        `\n${chalk.bold.cyan("Hodor - AI Code Review Agent")}`,
-      );
-      log(chalk.dim(`Platform: ${platform.toUpperCase()}`));
-      log(chalk.dim(`PR URL: ${prUrl}`));
+      log(`\n${chalk.bold.cyan("Hodor - AI Code Review Agent")}`);
+      if (localMode) {
+        log(chalk.dim(`Mode: Local diff review`));
+        log(chalk.dim(`Diff against: ${diffAgainst}`));
+        log(chalk.dim(`Workspace: ${workspace ?? process.cwd()}`));
+      } else {
+        log(chalk.dim(`Platform: ${platform.toUpperCase()}`));
+        log(chalk.dim(`PR URL: ${prUrl}`));
+      }
       log(chalk.dim(`Model: ${model}`));
       if (reasoningEffort) {
         log(chalk.dim(`Reasoning Effort: ${reasoningEffort}`));
@@ -211,22 +226,24 @@ program
 
       streamLog(chalk.dim("▶ Setting up workspace..."));
       const { review, metricsFooter, headSha, metrics } = await reviewPr({
-        prUrl,
+        prUrl: localMode ? undefined : prUrl,
         model,
         reasoningEffort,
         customPrompt: prompt,
         promptFile,
         cleanup: !workspace,
         workspaceDir: workspace,
-        includeMetricsFooter: post,
+        includeMetricsFooter: post && !localMode,
         onEvent: handleEvent,
         bedrockTags,
+        localMode,
+        diffAgainst,
       });
       const reviewText = renderMarkdown(review);
 
       streamLog(chalk.green("✔ Review complete!"));
 
-      if (post) {
+      if (post && prUrl) {
         log(chalk.cyan("\nPosting review to PR/MR..."));
 
         const result = await postReviewComment({
@@ -241,20 +258,16 @@ program
           log(chalk.bold.green("Review posted successfully!"));
           log(chalk.dim(`  ${platform === "github" ? "PR" : "MR"}: ${prUrl}`));
         } else {
-          log(
-            chalk.bold.red(`Failed to post review: ${result.error}`),
-          );
+          log(chalk.bold.red(`Failed to post review: ${result.error}`));
           log(chalk.yellow("\nReview output:\n"));
           console.log(reviewText);
         }
       } else {
         log(chalk.bold.green("Review Complete\n"));
         console.log(reviewText);
-        log(
-          chalk.dim(
-            "\nTip: Use --post to automatically post this review to the PR/MR",
-          ),
-        );
+        if (!localMode) {
+          log(chalk.dim("\nTip: Use --post to automatically post this review to the PR/MR"));
+        }
       }
 
       // Push metrics to Prometheus Pushgateway (best-effort, never fails the run)

src/prompt.ts

@@ -21,6 +21,7 @@ export function buildPrReviewPrompt(opts: {
   customPromptFile?: string | null;
   embeddedDiff?: string | null;
   previousReviewSha?: string | null;
+  localMode?: boolean;
 }): string {
   const {
     prUrl,
@@ -32,6 +33,7 @@ export function buildPrReviewPrompt(opts: {
     customPromptFile,
     embeddedDiff,
     previousReviewSha,
+    localMode = false,
   } = opts;
 
   // Step 1: Determine template (always tool submission; rendered to markdown post-hoc)
@@ -74,6 +76,10 @@ export function buildPrReviewPrompt(opts: {
     prDiffCmd = `git --no-pager diff ${previousReviewSha}...HEAD --name-only`;
     gitDiffCmd = `git --no-pager diff ${previousReviewSha}...HEAD`;
     logger.info(`Incremental review: diffing from ${previousReviewSha.slice(0, 8)} to HEAD`);
+  } else if (localMode) {
+    // Plain two-arg diff includes uncommitted (staged + unstaged) changes
+    prDiffCmd = `git --no-pager diff ${targetBranch} --name-only`;
+    gitDiffCmd = `git --no-pager diff ${targetBranch}`;
   } else if (platform === "github") {
     prDiffCmd = `git --no-pager diff origin/${targetBranch}...HEAD --name-only`;
     gitDiffCmd = `git --no-pager diff origin/${targetBranch}...HEAD`;