prq-cli 0.6.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

@@ -6732,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}`));
@@ -6775,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}`);
@@ -6784,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(`
@@ -6791,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.
 `);
@@ -6803,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);
@@ -6812,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":
@@ -6820,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;
         }
@@ -6877,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);
     });
   });
 }
@@ -11009,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({});

package/package.json

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