agent-reviews 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "agent-reviews",
+  "owner": {
+    "name": "Paul Bakaus"
+  },
+  "metadata": {
+    "description": "CLI and Claude Code skill for managing GitHub PR review comments"
+  },
+  "plugins": [
+    {
+      "name": "agent-reviews",
+      "source": "./",
+      "description": "Manage GitHub PR review comments — list, filter, reply, and watch for bot findings"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "agent-reviews",
+  "description": "Manage GitHub PR review comments from Claude Code. Automatically triage, fix, and respond to bot findings.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Paul Bakaus",
+    "url": "https://github.com/pbakaus"
+  },
+  "homepage": "https://github.com/pbakaus/agent-reviews",
+  "repository": "https://github.com/pbakaus/agent-reviews",
+  "license": "MIT",
+  "keywords": ["github", "pull-request", "code-review", "claude-code", "ai-agent", "review-bot"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paul Bakaus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# agent-reviews
+
+Manage GitHub PR review comments from the terminal and from AI coding agents.
+
+PR review bots (Copilot, Cursor Bugbot, CodeRabbit, etc.) leave inline comments on your pull requests. agent-reviews gives you a CLI to list, filter, reply to, and watch those comments — plus a Claude Code skill that automates the entire triage-fix-reply loop.
+
+## Install
+
+### CLI (npm)
+
+```bash
+npm install -g agent-reviews
+```
+
+### CLI (Homebrew)
+
+```bash
+brew install agent-reviews
+```
+
+### Claude Code skill
+
+Install as a skill for the full automated workflow — no npm install required:
+
+```bash
+npx skills add pbakaus/agent-reviews@agent-reviews
+```
+
+This registers the `/agent-reviews` slash command. When invoked, it uses `npx` to auto-download the CLI on first run.
+
+> You can also use both: install the CLI globally for direct terminal use, and the skill for the Claude Code workflow.
+
+## Authentication
+
+The primary authentication method is the **GitHub CLI** — if you're logged in with `gh auth login`, agent-reviews picks up the token automatically. No configuration needed.
+
+For environments where `gh` isn't available (such as Claude Code Cloud, which routes git through an HTTPS proxy), agent-reviews falls back to:
+
+1. `GITHUB_TOKEN` environment variable
+2. `.env.local` in the repo root
+
+The proxy environment is also why agent-reviews includes [undici](https://github.com/nodejs/undici) `ProxyAgent` support — when `HTTPS_PROXY` is set, GitHub API requests are routed through it automatically.
+
+**Resolution order** (first match wins):
+
+1. `GITHUB_TOKEN` environment variable
+2. `.env.local` in the repo root
+3. `gh auth token` (GitHub CLI)
+
+## CLI Usage
+
+```bash
+# List all review comments on the current branch's PR
+agent-reviews
+
+# Only unresolved comments
+agent-reviews --unresolved
+
+# Only unanswered bot comments
+agent-reviews --unanswered --bots-only
+
+# Full detail for a specific comment (diff hunk + replies)
+agent-reviews --detail 12345678
+
+# Reply to a comment
+agent-reviews --reply 12345678 "Fixed in abc1234"
+
+# JSON output for scripting / AI agents
+agent-reviews --json
+
+# Watch for new comments (polls every 30s, exits after 10 min idle)
+agent-reviews --watch --bots-only
+
+# Target a specific PR (otherwise auto-detects from branch)
+agent-reviews --pr 42
+```
+
+### Options
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--unresolved` | `-u` | Only unresolved/pending comments |
+| `--unanswered` | `-a` | Only comments without any replies |
+| `--reply <id> "msg"` | `-r` | Reply to a comment |
+| `--detail <id>` | `-d` | Full detail for a comment |
+| `--pr <number>` | `-p` | Target a specific PR |
+| `--json` | `-j` | JSON output |
+| `--bots-only` | `-b` | Only bot comments |
+| `--humans-only` | `-H` | Only human comments |
+| `--watch` | `-w` | Poll for new comments |
+| `--interval <sec>` | `-i` | Poll interval in seconds (default: 30) |
+| `--timeout <sec>` | | Inactivity timeout in seconds (default: 600) |
+
+## Claude Code Skill
+
+The `/agent-reviews` skill automates the full PR review bot workflow:
+
+1. Fetch all unanswered bot comments via `npx agent-reviews --bots-only --json`
+2. Evaluate each finding — true positive, false positive, or uncertain
+3. Fix real bugs and run lint/type-check
+4. Dismiss false positives with an explanation
+5. Reply to every comment with the outcome
+6. Watch for new comments as bots re-analyze the fixes
+7. Report a summary of all actions taken
+
+### Skill behavior
+
+- **True positives** get fixed, verified, and replied with `✅ Fixed in {commit}`
+- **False positives** get replied with `⚠️ Won't fix — {reason}`
+- **Uncertain findings** prompt the user via `AskUserQuestion`
+- All fixes are batched into a single commit before polling begins
+- Watch mode runs for up to 10 minutes, processing any new findings
+
+## How It Works
+
+### Comment types
+
+agent-reviews fetches three types of GitHub PR comments:
+
+| Type | Label | Description |
+|------|-------|-------------|
+| Review comment | `CODE` | Inline comment attached to a specific line |
+| Issue comment | `COMMENT` | General PR-level comment |
+| Review | `REVIEW` | Review summary (approved, changes requested) |
+
+### Meta-comment filtering
+
+Status updates from bots are automatically filtered out:
+
+- Vercel deployment status (`[vc]:...`)
+- Supabase branch status (`[supa]:...`)
+- Cursor Bugbot summary ("Cursor Bugbot has reviewed your changes...")
+
+Only actionable findings are shown.
+
+### Reply status
+
+Each comment displays its reply status:
+
+| Status | Meaning |
+|--------|---------|
+| `○ no reply` | No one has replied |
+| `✓ replied` | A human has replied |
+| `⚡ bot replied` | Only bots have replied |
+
+### Watch mode
+
+Polls the GitHub API at a configurable interval and reports new comments as they appear. Outputs both formatted text and JSON for AI agent consumption. Exits automatically after a configurable inactivity timeout (default: 10 minutes).
+
+## License
+
+MIT

package/bin/agent-reviews.js

@@ -0,0 +1,506 @@
+#!/usr/bin/env node
+
+/**
+ * agent-reviews — CLI for managing GitHub PR review comments
+ *
+ * List, filter, reply to, and watch PR review comments from the terminal.
+ * Designed for both human use and as a tool for AI coding agents.
+ *
+ * Usage:
+ *   agent-reviews                        # List all review comments
+ *   agent-reviews --unresolved           # List unresolved comments only
+ *   agent-reviews --unanswered           # List comments without replies
+ *   agent-reviews --reply <id> "msg"     # Reply to a specific comment
+ *   agent-reviews --detail <id>          # Show full detail (no truncation)
+ *   agent-reviews --json                 # Output as JSON for scripting
+ *   agent-reviews --watch                # Watch for new comments (poll mode)
+ *
+ * Options:
+ *   --pr <number>    Target specific PR (auto-detects from branch)
+ *   --bots-only      Only show bot comments
+ *   --humans-only    Only show human comments
+ */
+
+const {
+  getProxyFetch,
+  getGitHubToken,
+  getRepoInfo,
+  getCurrentBranch,
+} = require("../lib/github");
+
+const {
+  findPRForBranch,
+  fetchPRComments,
+  processComments,
+  filterComments,
+  replyToComment,
+} = require("../lib/comments");
+
+const {
+  colors,
+  formatComment,
+  formatDetailedComment,
+  formatOutput,
+} = require("../lib/format");
+
+const proxyFetch = getProxyFetch();
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const result = {
+    command: "list",
+    prNumber: null,
+    filter: null,
+    replyTo: null,
+    replyMessage: null,
+    json: false,
+    botsOnly: false,
+    humansOnly: false,
+    detail: null,
+    help: false,
+    version: false,
+    watch: false,
+    watchInterval: 30,
+    watchTimeout: 600,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case "--unresolved":
+      case "-u":
+        result.filter = "unresolved";
+        break;
+      case "--unanswered":
+      case "-a":
+        result.filter = "unanswered";
+        break;
+      case "--reply":
+      case "-r":
+        result.command = "reply";
+        result.replyTo = args[++i];
+        result.replyMessage = args[++i];
+        break;
+      case "--pr":
+      case "-p":
+        result.prNumber = Number.parseInt(args[++i], 10);
+        break;
+      case "--json":
+      case "-j":
+        result.json = true;
+        break;
+      case "--bots-only":
+      case "-b":
+        result.botsOnly = true;
+        break;
+      case "--humans-only":
+      case "-H":
+        result.humansOnly = true;
+        break;
+      case "--detail":
+      case "-d":
+        result.command = "detail";
+        result.detail = args[++i];
+        break;
+      case "--watch":
+      case "-w":
+        result.watch = true;
+        result.command = "watch";
+        break;
+      case "--interval":
+      case "-i":
+        result.watchInterval = Number.parseInt(args[++i], 10);
+        break;
+      case "--exit-after":
+      case "--timeout":
+        result.watchTimeout = Number.parseInt(args[++i], 10);
+        break;
+      case "--help":
+      case "-h":
+        result.help = true;
+        break;
+      case "--version":
+      case "-v":
+        result.version = true;
+        break;
+      default:
+        break;
+    }
+  }
+
+  return result;
+}
+
+function showHelp() {
+  console.log(`
+${colors.bright}agent-reviews${colors.reset} — Manage PR review comments from the CLI
+
+Designed for both human use and as a tool for AI coding agents (Claude Code, etc.).
+
+${colors.bright}Usage:${colors.reset}
+  agent-reviews                        List all review comments
+  agent-reviews --unresolved           List unresolved comments only
+  agent-reviews --unanswered           List comments without replies
+  agent-reviews --reply <id> "msg"     Reply to a specific comment
+  agent-reviews --detail <id>          Show full detail for a comment
+  agent-reviews --watch                Watch for new comments (poll mode)
+  agent-reviews --json                 Output as JSON for scripting
+
+${colors.bright}Options:${colors.reset}
+  -u, --unresolved   Show only unresolved/pending comments
+  -a, --unanswered   Show only comments without any replies
+  -r, --reply        Reply to a comment (requires ID and message)
+  -d, --detail       Show full detail for a specific comment
+  -p, --pr           Target specific PR number (auto-detects from branch)
+  -j, --json         Output as JSON instead of formatted text
+  -b, --bots-only    Only show comments from bots
+  -H, --humans-only  Only show comments from humans
+  -h, --help         Show this help
+  -v, --version      Show version
+
+${colors.bright}Watch Mode:${colors.reset}
+  -w, --watch        Poll for new comments periodically
+  -i, --interval     Poll interval in seconds (default: 30)
+  --timeout          Exit after N seconds of inactivity (default: 600)
+
+${colors.bright}Examples:${colors.reset}
+  agent-reviews                              # Show all comments
+  agent-reviews -u                           # Show unresolved only
+  agent-reviews -a --bots-only               # Unanswered bot comments
+  agent-reviews --reply 12345 "Fixed!"       # Reply to comment #12345
+  agent-reviews --detail 12345               # Full detail for a comment
+  agent-reviews --detail 12345 --json        # Detail as JSON
+  agent-reviews --json | jq '.[]'            # Pipe to jq
+  agent-reviews --watch --bots-only          # Watch for new bot comments
+  agent-reviews -w -i 15 --timeout 300       # Poll every 15s, exit after 5 min
+
+${colors.bright}Authentication:${colors.reset}
+  Set GITHUB_TOKEN env var, or use 'gh auth login' (gh CLI).
+
+${colors.dim}Comment IDs are shown in brackets, e.g., [12345678]${colors.reset}
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Watch mode
+// ---------------------------------------------------------------------------
+
+function formatTimestamp() {
+  return new Date().toISOString().replace("T", " ").slice(0, 19);
+}
+
+function sleep(seconds) {
+  return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+}
+
+async function watchForComments(context, options) {
+  const { owner, repo, prNumber, prUrl, token } = context;
+  const seenIds = new Set();
+  let lastActivityTime = Date.now();
+  let pollCount = 0;
+
+  function getWatchFilterDesc() {
+    if (options.botsOnly) return "bots-only";
+    if (options.humansOnly) return "humans-only";
+    return "all";
+  }
+  const filterDesc = getWatchFilterDesc();
+
+  console.log(
+    `\n${colors.bright}=== PR Comments Watch Mode ===${colors.reset}`
+  );
+  console.log(`${colors.dim}PR #${prNumber}: ${prUrl}${colors.reset}`);
+  console.log(
+    `${colors.dim}Polling every ${options.watchInterval}s, exit after ${options.watchTimeout}s of inactivity${colors.reset}`
+  );
+  console.log(
+    `${colors.dim}Filters: ${filterDesc}, ${options.filter || "all comments"}${colors.reset}`
+  );
+  console.log(
+    `${colors.dim}Started at ${formatTimestamp()}${colors.reset}\n`
+  );
+
+  // Initial fetch to populate seen IDs
+  const initialData = await fetchPRComments(
+    owner,
+    repo,
+    prNumber,
+    token,
+    proxyFetch
+  );
+  const initialProcessed = processComments(initialData);
+  const initialFiltered = filterComments(initialProcessed, options);
+
+  for (const comment of initialFiltered) {
+    seenIds.add(comment.id);
+  }
+
+  console.log(
+    `${colors.dim}[${formatTimestamp()}] Initial state: ${initialFiltered.length} existing comments tracked${colors.reset}`
+  );
+
+  if (initialFiltered.length > 0) {
+    console.log(`\n${colors.yellow}=== EXISTING COMMENTS ===${colors.reset}`);
+    for (const comment of initialFiltered) {
+      console.log(formatComment(comment));
+      console.log("");
+    }
+  }
+
+  // Watch loop
+  while (true) {
+    await sleep(options.watchInterval);
+    pollCount++;
+
+    const rawData = await fetchPRComments(
+      owner,
+      repo,
+      prNumber,
+      token,
+      proxyFetch
+    );
+    const processed = processComments(rawData);
+    const filtered = filterComments(processed, options);
+
+    const newComments = filtered.filter((c) => !seenIds.has(c.id));
+
+    if (newComments.length > 0) {
+      lastActivityTime = Date.now();
+
+      console.log(
+        `\n${colors.green}=== NEW COMMENTS DETECTED [${formatTimestamp()}] ===${colors.reset}`
+      );
+      console.log(
+        `${colors.bright}Found ${newComments.length} new comment${newComments.length === 1 ? "" : "s"}${colors.reset}\n`
+      );
+
+      for (const comment of newComments) {
+        seenIds.add(comment.id);
+        console.log(formatComment(comment));
+        console.log("");
+      }
+
+      // JSON output for AI agent parsing
+      console.log(`${colors.dim}--- JSON for processing ---${colors.reset}`);
+      console.log(JSON.stringify(newComments, null, 2));
+      console.log(`${colors.dim}--- end JSON ---${colors.reset}\n`);
+    } else {
+      const inactiveSeconds = Math.round(
+        (Date.now() - lastActivityTime) / 1000
+      );
+      console.log(
+        `${colors.dim}[${formatTimestamp()}] Poll #${pollCount}: No new comments (${inactiveSeconds}s/${options.watchTimeout}s idle)${colors.reset}`
+      );
+
+      if (inactiveSeconds >= options.watchTimeout) {
+        console.log(`\n${colors.green}=== WATCH COMPLETE ===${colors.reset}`);
+        console.log(
+          `${colors.dim}No new comments after ${options.watchTimeout}s of inactivity.${colors.reset}`
+        );
+        console.log(
+          `${colors.dim}Total comments tracked: ${seenIds.size}${colors.reset}`
+        );
+        console.log(
+          `${colors.dim}Exiting at ${formatTimestamp()}${colors.reset}`
+        );
+        return;
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const options = parseArgs();
+
+  if (options.version) {
+    const pkg = require("../package.json");
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
+  if (options.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  // Get GitHub token
+  const token = getGitHubToken();
+  if (!token) {
+    console.error(`${colors.red}Error: GitHub token not found${colors.reset}`);
+    console.error(
+      "Set GITHUB_TOKEN env var, or authenticate with: gh auth login"
+    );
+    process.exit(1);
+  }
+
+  // Get repo info
+  const repoInfo = getRepoInfo();
+  if (!repoInfo) {
+    console.error(
+      `${colors.red}Error: Could not determine repository from git remote${colors.reset}`
+    );
+    process.exit(1);
+  }
+
+  // Find PR
+  let prNumber = options.prNumber;
+  let prUrl = null;
+
+  if (!prNumber) {
+    const branch = getCurrentBranch();
+    if (!branch) {
+      console.error(
+        `${colors.red}Error: Could not determine current branch${colors.reset}`
+      );
+      process.exit(1);
+    }
+
+    if (!options.json) {
+      console.log(
+        `${colors.dim}Finding PR for branch: ${branch}...${colors.reset}`
+      );
+    }
+
+    const pr = await findPRForBranch(
+      repoInfo.owner,
+      repoInfo.repo,
+      branch,
+      token,
+      proxyFetch
+    );
+    if (!pr) {
+      console.error(
+        `${colors.red}Error: No open PR found for branch '${branch}'${colors.reset}`
+      );
+      process.exit(1);
+    }
+
+    prNumber = pr.number;
+    prUrl = pr.html_url;
+  }
+
+  // Handle reply command
+  if (options.command === "reply") {
+    if (!(options.replyTo && options.replyMessage)) {
+      console.error(
+        `${colors.red}Error: --reply requires comment ID and message${colors.reset}`
+      );
+      console.error('Usage: agent-reviews --reply <id> "message"');
+      process.exit(1);
+    }
+
+    if (!options.json) {
+      console.log(
+        `${colors.dim}Replying to comment ${options.replyTo}...${colors.reset}`
+      );
+    }
+
+    const result = await replyToComment(
+      repoInfo.owner,
+      repoInfo.repo,
+      prNumber,
+      options.replyTo,
+      options.replyMessage,
+      token,
+      proxyFetch
+    );
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(
+        `${colors.green}✓ Reply posted successfully${colors.reset}`
+      );
+      console.log(`  ${colors.dim}${result.html_url}${colors.reset}`);
+    }
+
+    return;
+  }
+
+  // Handle detail command
+  if (options.command === "detail") {
+    if (!options.detail) {
+      console.error(
+        `${colors.red}Error: --detail requires a comment ID${colors.reset}`
+      );
+      process.exit(1);
+    }
+
+    if (!options.json) {
+      console.log(
+        `${colors.dim}Fetching comments for PR #${prNumber}...${colors.reset}`
+      );
+    }
+
+    const rawData = await fetchPRComments(
+      repoInfo.owner,
+      repoInfo.repo,
+      prNumber,
+      token,
+      proxyFetch
+    );
+    const processed = processComments(rawData);
+    const targetId = Number(options.detail);
+    const comment = processed.find((c) => c.id === targetId);
+
+    if (!comment) {
+      console.error(
+        `${colors.red}Error: Comment ${options.detail} not found in PR #${prNumber}${colors.reset}`
+      );
+      process.exit(1);
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(comment, null, 2));
+    } else {
+      console.log(formatDetailedComment(comment));
+    }
+
+    return;
+  }
+
+  // Handle watch command
+  if (options.command === "watch") {
+    await watchForComments(
+      { owner: repoInfo.owner, repo: repoInfo.repo, prNumber, prUrl, token },
+      options
+    );
+    return;
+  }
+
+  // Default: fetch and display comments
+  if (!options.json) {
+    console.log(
+      `${colors.dim}Fetching comments for PR #${prNumber}...${colors.reset}`
+    );
+  }
+
+  const rawData = await fetchPRComments(
+    repoInfo.owner,
+    repoInfo.repo,
+    prNumber,
+    token,
+    proxyFetch
+  );
+
+  const processed = processComments(rawData);
+  const filtered = filterComments(processed, options);
+
+  console.log(formatOutput(filtered, options));
+
+  if (!options.json && prUrl) {
+    console.log(`\n${colors.dim}PR: ${prUrl}${colors.reset}`);
+  }
+}
+
+main().catch((error) => {
+  console.error(`${colors.red}Error: ${error.message}${colors.reset}`);
+  process.exit(1);
+});