prq-cli 0.5.0 → 0.7.0

package/README.md

@@ -4,7 +4,7 @@
 
 PR Queue — see what code reviews need your attention.
 
-A CLI tool that queries GitHub and shows you a categorized view of PRs that need action. No more missing review requests because someone forgot to re-request, no more stale PRs sitting idle.
+A CLI tool that shows you a categorized view of PRs that need action — then lets you act on them with whatever tools you already use. PRQ is the queue. You bring the workflow.
 
 ## Install
 
@@ -17,83 +17,169 @@ Requires [GitHub CLI](https://cli.github.com/) (`gh`) to be authenticated.
 ## Quick Start
 
 ```bash
-# See your review queue
+# See your review queue (interactive by default)
 prq
 
-# Interactive mode — navigate with arrow keys, act with shortcuts
-prq -i
+# Non-interactive / plain text
+prq --no-interactive
+
+# Act on a PR
+prq review 482
+prq open 482
+prq nudge 482
 ```
 
 ## Commands
 
 ### `prq status` (default)
 
-Shows PRs needing your attention, grouped into four categories:
+Shows PRs needing your attention in four categories:
 
-- **Needs Re-review** — you left a review, but new commits were pushed after
-- **Requested Reviews** — you're a requested reviewer and haven't reviewed yet
-- **Stale** — PRs you're involved in with no activity for N days
-- **Your PRs Waiting** — PRs you authored that are waiting on someone else
+- **◆ Needs Re-review** — new commits pushed after your review
+- **● Requested** — you're a requested reviewer
+- **○ Stale** — no activity for N days
+- **◇ Your PRs Waiting** — waiting on someone else
 
 ```bash
-prq                                        # all repos you have access to
+prq                                        # interactive mode (default)
 prq status --repos org/repo1 org/repo2     # specific repos
-prq status --stale-days 7                  # custom stale threshold
-prq status --json                          # machine-readable output
-prq status -i                              # interactive mode
+prq status --stale-days 7                  # custom threshold
+prq status --json                          # machine-readable
+prq --no-interactive                       # plain text output
 ```
 
-### Interactive Mode
+### Interactive Mode (default)
 
-Run `prq -i` to navigate your queue with keyboard shortcuts:
+Interactive mode is the default when running in a terminal. Navigate your queue with keyboard shortcuts:
 
-- **↑↓** navigate between PRs
-- **r** review — open files changed tab
-- **o** open — open PR in browser
-- **n** nudge — post a comment
-- **c** copy URL to clipboard
-- **q** quit
+| Key | Action |
+|-----|--------|
+| ↑↓ | Navigate between PRs |
+| r | Review — open files changed |
+| o | Open — open PR in browser |
+| n | Nudge — post a comment |
+| c | Copy URL to clipboard |
+| a | Actions — open menu with all actions |
+| q | Quit |
 
-### `prq open <identifier>`
+Press **a** to open the actions menu, which lists all actions (built-in and custom from your config). Press **1-9** to run an action, or **q** to dismiss.
 
-Open a PR in the browser.
+### `prq open/review/nudge <identifier>`
+
+Act on PRs by number, `org/repo#number`, or full URL:
 
 ```bash
-prq open 482                               # searches your queue for PR #482
-prq open superdoc-dev/superdoc#482         # opens directly
-prq open https://github.com/org/repo/pull/482
+prq open 482                               # open in browser
+prq review 482                             # open files changed
+prq nudge 482                              # post a comment
+prq nudge 482 --yes --message "Update?"    # skip confirmation
 ```
 
-### `prq review <identifier>`
+### `prq run <action> <identifier>`
 
-Open a PR's "Files changed" tab for review.
+Run any custom action you've defined:
 
 ```bash
-prq review 482
-prq review superdoc-dev/superdoc#482
+prq run checkout 482
+prq run ai-review 482
 ```
 
-### `prq nudge <identifier>`
+### `prq skill`
 
-Post a comment on a PR asking if it's still active.
+Install the `/prq` skill for Claude Code:
 
 ```bash
-prq nudge 482                              # confirm before posting
-prq nudge 482 --yes                        # skip confirmation
-prq nudge 482 --message "Any updates?"     # custom message
+prq skill            # install in current project
+prq skill --global   # install globally
 ```
 
-### `prq run <action> <identifier>`
+## Pluggable Actions
+
+PRQ doesn't force a workflow. Every action is a configurable shell command template. Override the defaults or add your own in `.prqrc.json`:
+
+### Use Claude Code for reviews
+
+```json
+{
+  "actions": {
+    "review": "claude -p '/review {url}'"
+  }
+}
+```
+
+Now `prq review 482` dispatches to Claude Code.
+
+### Use Codex for reviews
+
+```json
+{
+  "actions": {
+    "review": "codex exec --full-auto 'review the PR at {url}'"
+  }
+}
+```
+
+### Use gh CLI to checkout
+
+```json
+{
+  "actions": {
+    "checkout": "gh pr checkout {number} --repo {owner}/{repo}"
+  }
+}
+```
+
+Then `prq run checkout 482`.
 
-Run a custom action defined in your config.
+### Just open in browser (default)
+
+With no config, `prq review` opens the files changed tab and `prq open` opens the PR page. Zero setup needed.
+
+### Template variables
+
+| Variable | Example |
+|----------|---------|
+| `{url}` | `https://github.com/org/repo/pull/482` |
+| `{number}` | `482` |
+| `{owner}` | `org` |
+| `{repo}` | `repo` |
+| `{title}` | `fix: handle edge case` |
+| `{author}` | `alice` |
+| `{days}` | `5` |
+
+## Agent & Automation
+
+PRQ is fully scriptable with `--json` output and `--yes` flags:
 
 ```bash
-prq run checkout 482
+# Agent reads the queue
+prq status --json
+
+# Agent nudges all stale PRs
+prq status --json | jq -r '.prs[] | select(.category == "stale") | .number' \
+  | xargs -I{} prq nudge {} --yes
+
+# Claude Code cron
+prq status --json | claude -p "Review needs-re-review PRs older than 7 days"
 ```
 
-### `prq init`
+### Claude Code Skill
+
+Install the `/prq` skill to use PRQ inside Claude Code sessions:
+
+```bash
+prq skill --global
+```
+
+Then in Claude Code:
+
+```
+/prq                    → show queue, ask what to do
+"review 2439"           → dispatches to your configured review action
+"nudge all stale PRs"   → batch nudge
+```
 
-Creates a `.prqrc.json` config file in the current directory.
+The skill reads your `.prqrc.json` actions — if you have `/review` configured, it uses that. If not, it falls back to opening the browser.
 
 ## Configuration
 
@@ -103,7 +189,7 @@ Config is loaded in this order (later overrides earlier):
 2. `.prqrc.json` — per-project config
 3. CLI flags
 
-Example `.prqrc.json`:
+Full example:
 
 ```json
 {
@@ -111,25 +197,12 @@ Example `.prqrc.json`:
   "staleDays": 5,
   "actions": {
     "review": "claude -p '/review {url}'",
-    "checkout": "gh pr checkout {number} --repo {owner}/{repo}"
+    "checkout": "gh pr checkout {number} --repo {owner}/{repo}",
+    "approve": "gh pr review {number} --repo {owner}/{repo} --approve"
   }
 }
 ```
 
-### Custom Actions
-
-Actions are shell command templates with variables:
-
-- `{url}` — full PR URL
-- `{number}` — PR number
-- `{owner}` — repo owner
-- `{repo}` — repo name
-- `{title}` — PR title
-- `{author}` — PR author
-- `{days}` — days since last activity
-
-Default actions (`open`, `review`, `nudge`) can be overridden. Custom actions are available via `prq run <action>` and in interactive mode.
-
 ## License
 
 MIT

package/dist/bin/prq.js

@@ -6478,6 +6478,122 @@ Available actions: ${available}`);
   await executeCommand(command);
 }
 
+// src/commands/skill.ts
+var SKILL_CONTENT = `---
+name: prq
+description: PR review queue manager. Use when the user wants to check their PR review queue, review PRs, nudge stale PRs, or manage code review workflow. Triggers on mentions of "review queue", "PRs waiting", "stale PRs", "what needs review", or "prq".
+---
+
+# PRQ — PR Review Queue
+
+You have access to the \`prq\` CLI tool installed on this machine. Use it to help the user manage their code review queue.
+
+## Step 1: Get the queue
+
+Run this command to get the user's current review queue:
+
+\`\`\`bash
+prq status --json
+\`\`\`
+
+This returns a JSON object with categorized PRs:
+- **needs-re-review** — PRs where the user left a review but new commits were pushed after
+- **requested** — PRs where the user is a requested reviewer
+- **stale** — PRs with no activity for N days
+- **waiting-on-others** — PRs the user authored that are waiting on someone else
+
+## Step 2: Present the queue
+
+Show the results in a clear, scannable format grouped by category. For each PR, show:
+- The category symbol (◆ needs re-review, ● requested, ○ stale, ◇ waiting)
+- The repo and PR number
+- The title
+- The detail (e.g., "new commits since your review 2d ago")
+
+Then ask what the user wants to do.
+
+## Step 3: Act on PRs
+
+When the user asks to act on a PR, check the \`.prqrc.json\` file in the current directory (or \`~/.config/prq/config.json\`) for custom actions:
+
+\`\`\`json
+{
+  "actions": {
+    "review": "/review {url}",
+    "nudge": "shell:prq nudge {number} --yes"
+  }
+}
+\`\`\`
+
+### Action resolution
+
+For each action template:
+- **Starts with \`/\`** — it's a Claude Code skill. Invoke it by running the skill with the interpolated value. For example, \`/review https://github.com/org/repo/pull/123\`
+- **Starts with \`shell:\`** — it's a shell command. Run it with the Bash tool. For example, \`prq nudge 123 --yes\`
+- **Otherwise** — treat it as a prompt. Send it as a message.
+
+### Template variables
+
+Replace these in the action template:
+- \`{url}\` — full PR URL
+- \`{number}\` — PR number
+- \`{owner}\` — repo owner
+- \`{repo}\` — repo name
+- \`{title}\` — PR title
+- \`{author}\` — PR author
+
+### Default actions (if no config found)
+
+If no actions are configured, use these defaults:
+- **review** — invoke \`/review {url}\` if the /review skill exists, otherwise run \`prq review {number}\` to open files changed in browser
+- **nudge** — run \`prq nudge {number} --yes\`
+- **open** — run \`prq open {number}\`
+
+## Step 4: Batch operations
+
+If the user says things like "review all needs-re-review PRs" or "nudge all stale PRs":
+
+1. Filter the queue JSON by the requested category
+2. Confirm the list with the user: "I'll review these 3 PRs: #2439, #2380, #2352. Proceed?"
+3. Execute the action on each PR sequentially
+
+## Examples
+
+**User:** "check my review queue"
+→ Run \`prq status --json\`, present results, ask what to do
+
+**User:** "review 2439"
+→ Look up action for "review", interpolate with PR data, execute
+
+**User:** "nudge all stale PRs"
+→ Filter stale PRs from queue, confirm, run nudge on each
+
+**User:** "what PRs are waiting on me?"
+→ Run \`prq status --json\`, show only needs-re-review and requested categories
+
+**User:** "/prq" with no context
+→ Run \`prq status --json\`, present full queue, ask what to do
+`;
+function skillCommand(global) {
+  if (global) {
+    const fs2 = __require("node:fs");
+    const path2 = __require("node:path");
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    const skillDir = path2.join(home, ".claude", "skills", "prq");
+    const skillPath = path2.join(skillDir, "SKILL.md");
+    fs2.mkdirSync(skillDir, { recursive: true });
+    fs2.writeFileSync(skillPath, SKILL_CONTENT);
+    console.log(`Installed to ${skillPath}`);
+  } else {
+    const fs2 = __require("node:fs");
+    const skillDir = ".claude/skills/prq";
+    const skillPath = `${skillDir}/SKILL.md`;
+    fs2.mkdirSync(skillDir, { recursive: true });
+    fs2.writeFileSync(skillPath, SKILL_CONTENT);
+    console.log(`Installed to ${skillPath}`);
+  }
+}
+
 // src/categorize.ts
 function timeAgo(dateStr) {
   const now = Date.now();
@@ -6616,7 +6732,8 @@ function toResolvedPR(pr) {
     updatedAt: pr.updatedAt
   };
 }
-function render(result, selectedIndex, message) {
+function render(state) {
+  const { result, selectedIndex, message, actionMenu } = state;
   process.stdout.write("\x1B[2J\x1B[H");
   const lines = [];
   lines.push(source_default.bold(` PRQ Status for ${result.user}`));
@@ -6659,8 +6776,20 @@ function render(result, selectedIndex, message) {
   }
   lines.push("");
   lines.push(source_default.dim(` ${"─".repeat(50)}`));
-  lines.push("");
-  lines.push(` ${source_default.dim("↑↓")} navigate  ${source_default.white("r")} review  ${source_default.white("o")} open  ${source_default.white("n")} nudge  ${source_default.white("c")} copy url  ${source_default.white("q")} quit`);
+  if (actionMenu) {
+    const pr = result.prs[selectedIndex];
+    lines.push("");
+    lines.push(` ${source_default.bold("Actions")} for ${source_default.white(`#${pr.number}`)}`);
+    lines.push("");
+    for (let i = 0;i < actionMenu.length; i++) {
+      lines.push(`   ${source_default.white(String(i + 1))}. ${actionMenu[i].name}`);
+    }
+    lines.push("");
+    lines.push(` ${source_default.dim("1-9")} run action  ${source_default.white("q")} back`);
+  } else {
+    lines.push("");
+    lines.push(` ${source_default.dim("↑↓")} navigate  ${source_default.white("r")} review  ${source_default.white("o")} open  ${source_default.white("n")} nudge  ${source_default.white("c")} copy url  ${source_default.white("a")} actions  ${source_default.white("q")} quit`);
+  }
   if (message) {
     lines.push("");
     lines.push(` ${message}`);
@@ -6668,6 +6797,17 @@ function render(result, selectedIndex, message) {
   process.stdout.write(lines.join(`
 `));
 }
+async function runAction(actionName, template, pr, state) {
+  const cmd = interpolate(template, buildContext(toResolvedPR(pr)));
+  state.message = source_default.dim(`running ${actionName} on ${pr.repo}#${pr.number}...`);
+  render(state);
+  try {
+    await executeCommand(cmd);
+    return source_default.green(`${actionName}: ${pr.repo}#${pr.number}`);
+  } catch {
+    return source_default.red(`${actionName} failed`);
+  }
+}
 async function interactiveMode(result, config) {
   if (result.prs.length === 0) {
     console.log(source_default.green(`
@@ -6675,9 +6815,14 @@ async function interactiveMode(result, config) {
 `));
     return;
   }
-  let selectedIndex = 0;
-  let message = "";
   const total = result.prs.length;
+  const allActions = listActions(config);
+  const state = {
+    result,
+    selectedIndex: 0,
+    message: "",
+    actionMenu: null
+  };
   if (!process.stdin.isTTY) {
     process.stdout.write(`Interactive mode requires a terminal. Use prq status instead.
 `);
@@ -6687,7 +6832,7 @@ async function interactiveMode(result, config) {
   process.stdin.resume();
   process.stdin.setEncoding("utf8");
   process.stdout.write("\x1B[?25l");
-  render(result, selectedIndex, message);
+  render(state);
   return new Promise((resolve) => {
     const cleanup = () => {
       process.stdin.setRawMode(false);
@@ -6696,7 +6841,26 @@ async function interactiveMode(result, config) {
       process.stdout.write("\x1B[?25h\x1B[2J\x1B[H");
     };
     process.stdin.on("data", async (key) => {
-      const pr = result.prs[selectedIndex];
+      const pr = result.prs[state.selectedIndex];
+      if (state.actionMenu) {
+        if (key === "q" || key === "\x1B" || key === "a") {
+          state.actionMenu = null;
+          state.message = "";
+        } else if (key === "\x03") {
+          cleanup();
+          resolve();
+          return;
+        } else {
+          const idx = parseInt(key, 10);
+          if (idx >= 1 && idx <= state.actionMenu.length) {
+            const action = state.actionMenu[idx - 1];
+            state.message = await runAction(action.name, action.template, pr, state);
+            state.actionMenu = null;
+          }
+        }
+        render(state);
+        return;
+      }
       switch (key) {
         case "q":
         case "\x03":
@@ -6704,55 +6868,31 @@ async function interactiveMode(result, config) {
           resolve();
           return;
         case "\x1B[A":
-          selectedIndex = Math.max(0, selectedIndex - 1);
-          message = "";
+          state.selectedIndex = Math.max(0, state.selectedIndex - 1);
+          state.message = "";
           break;
         case "\x1B[B":
-          selectedIndex = Math.min(total - 1, selectedIndex + 1);
-          message = "";
+          state.selectedIndex = Math.min(total - 1, state.selectedIndex + 1);
+          state.message = "";
           break;
         case "o": {
-          const template = getAction("open", config);
+          const template = allActions.open;
           if (template) {
-            const cmd = interpolate(template, buildContext(toResolvedPR(pr)));
-            message = source_default.dim(`opening ${pr.repo}#${pr.number}...`);
-            render(result, selectedIndex, message);
-            try {
-              await executeCommand(cmd);
-              message = source_default.green(`opened ${pr.repo}#${pr.number}`);
-            } catch {
-              message = source_default.red("failed to open");
-            }
+            state.message = await runAction("open", template, pr, state);
           }
           break;
         }
         case "r": {
-          const template = getAction("review", config);
+          const template = allActions.review;
           if (template) {
-            const cmd = interpolate(template, buildContext(toResolvedPR(pr)));
-            message = source_default.dim(`opening review for ${pr.repo}#${pr.number}...`);
-            render(result, selectedIndex, message);
-            try {
-              await executeCommand(cmd);
-              message = source_default.green(`opened review for ${pr.repo}#${pr.number}`);
-            } catch {
-              message = source_default.red("failed to open review");
-            }
+            state.message = await runAction("review", template, pr, state);
           }
           break;
         }
         case "n": {
-          const template = getAction("nudge", config);
+          const template = allActions.nudge;
           if (template) {
-            const cmd = interpolate(template, buildContext(toResolvedPR(pr)));
-            message = source_default.dim(`nudging ${pr.repo}#${pr.number}...`);
-            render(result, selectedIndex, message);
-            try {
-              await executeCommand(cmd);
-              message = source_default.green(`nudged ${pr.repo}#${pr.number}`);
-            } catch {
-              message = source_default.red("failed to nudge");
-            }
+            state.message = await runAction("nudge", template, pr, state);
           }
           break;
         }
@@ -6761,16 +6901,25 @@ async function interactiveMode(result, config) {
           try {
             const proc = process.platform === "darwin" ? "pbcopy" : process.platform === "linux" ? "xclip -selection clipboard" : "clip";
             await executeCommand(`echo "${url}" | ${proc}`);
-            message = source_default.green("url copied");
+            state.message = source_default.green("url copied");
           } catch {
-            message = source_default.dim(url);
+            state.message = source_default.dim(url);
           }
           break;
         }
+        case "a": {
+          const entries = Object.entries(allActions);
+          state.actionMenu = entries.map(([name, template]) => ({
+            name,
+            template
+          }));
+          state.message = "";
+          break;
+        }
         default:
           break;
       }
-      render(result, selectedIndex, message);
+      render(state);
     });
   });
 }
@@ -10893,12 +11042,12 @@ function getVersion() {
 function createCLI() {
   const program2 = new Command;
   program2.name("prq").description("PR Queue — see what code reviews need your attention").version(getVersion());
-  program2.command("status", { isDefault: true }).description("Show PRs needing your attention").option("-r, --repos <repos...>", "Filter to specific repos (owner/name)").option("-s, --stale-days <days>", "Days of inactivity to consider stale", "3").option("--json", "Output as JSON").option("-i, --interactive", "Interactive mode with keyboard shortcuts").action(async (opts) => {
+  program2.command("status", { isDefault: true }).description("Show PRs needing your attention").option("-r, --repos <repos...>", "Filter to specific repos (owner/name)").option("-s, --stale-days <days>", "Days of inactivity to consider stale", "3").option("--json", "Output as JSON").option("--no-interactive", "Disable interactive mode").action(async (opts) => {
     const config = loadConfig({
       repos: opts.repos,
       staleDays: opts.staleDays ? parseInt(opts.staleDays, 10) : undefined
     });
-    await statusCommand(config, opts.json ?? false, opts.interactive ?? false);
+    await statusCommand(config, opts.json ?? false, opts.interactive ?? true);
   });
   program2.command("open <identifier>").description("Open a PR in the browser").action(async (identifier) => {
     const config = loadConfig({});
@@ -10919,6 +11068,9 @@ function createCLI() {
     const config = loadConfig({});
     await runCommand(action, identifier, config);
   });
+  program2.command("skill").description("Install the /prq skill for Claude Code").option("-g, --global", "Install globally (~/.claude/skills/prq/)").action((opts) => {
+    skillCommand(opts.global ?? false);
+  });
   program2.command("init").description("Create config file interactively").action(async () => {
     await initCommand();
   });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "prq-cli",
-	"version": "0.5.0",
+	"version": "0.7.0",
 	"description": "PR Queue — see what code reviews need your attention",
 	"type": "module",
 	"bin": {