prq-cli 0.6.0 → 0.8.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,185 @@ 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)
+
+Interactive mode is the default when running in a terminal. Navigate your queue with keyboard shortcuts:
 
-Run `prq -i` to navigate your queue with keyboard shortcuts:
+| 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 |
 
-- **↑↓** 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
+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.
 
-### `prq open <identifier>`
+### `prq open/review/nudge <identifier>`
 
-Open a PR in the browser.
+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 — inline commands or scripts. Override the defaults or add your own in `.prqrc.json`.
+
+Actions run with full terminal control. When you trigger an action, prq suspends its TUI, the command takes over the screen (interactive tools like Claude Code work as normal), and prq resumes when the command exits.
+
+### Use Claude Code for reviews
+
+```json
+{
+  "actions": {
+    "review": "claude '/review {url}'"
+  }
+}
+```
+
+Now `prq review 482` opens an interactive Claude Code session.
+
+### Use Codex for reviews
+
+```json
+{
+  "actions": {
+    "review": "codex exec --full-auto 'review the PR at {url}'"
+  }
+}
+```
+
+### Use a script for complex workflows
+
+```json
+{
+  "actions": {
+    "review": "./scripts/review.sh {number} {url}"
+  }
+}
+```
+
+The script handles its own logic — session management, resuming, branching, whatever you need.
+
+### Use gh CLI to checkout
+
+```json
+{
+  "actions": {
+    "checkout": "gh pr checkout {number} --repo {owner}/{repo}"
+  }
+}
+```
+
+Then `prq run checkout 482`.
+
+### 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` |
+| `{fullRepo}` | `org/repo` |
+| `{title}` | `fix: handle edge case` |
+| `{author}` | `alice` |
+| `{days}` | `5` |
+| `{category}` | `needs-re-review` |
+
+## Agent & Automation
 
-Run a custom action defined in your config.
+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"
+```
+
+### Claude Code Skill
+
+Install the `/prq` skill to use PRQ inside Claude Code sessions:
+
+```bash
+prq skill --global
 ```
 
-### `prq init`
+Then in Claude Code:
 
-Creates a `.prqrc.json` config file in the current directory.
+```
+/prq                    → show queue, ask what to do
+"review 2439"           → dispatches to your configured review action
+"nudge all stale PRs"   → batch nudge
+```
+
+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,33 +205,20 @@ Config is loaded in this order (later overrides earlier):
 2. `.prqrc.json` — per-project config
 3. CLI flags
 
-Example `.prqrc.json`:
+Full example:
 
 ```json
 {
   "repos": ["org/repo1", "org/repo2"],
   "staleDays": 5,
   "actions": {
-    "review": "claude -p '/review {url}'",
-    "checkout": "gh pr checkout {number} --repo {owner}/{repo}"
+    "review": "claude '/review {url}'",
+    "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

@@ -6424,7 +6424,7 @@ function getAction(name, config) {
 function listActions(config) {
   return { ...DEFAULT_ACTIONS, ...config.actions };
 }
-function buildContext(pr) {
+function buildContext(pr, category = "") {
   const days = Math.floor((Date.now() - new Date(pr.updatedAt || Date.now()).getTime()) / 86400000);
   return {
     url: pr.url,
@@ -6434,7 +6434,8 @@ function buildContext(pr) {
     fullRepo: `${pr.owner}/${pr.repo}`,
     title: pr.title,
     author: pr.author,
-    days
+    days,
+    category
   };
 }
 function interpolate(template, context) {
@@ -6732,7 +6733,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 +6777,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 +6798,37 @@ function render(result, selectedIndex, message) {
   process.stdout.write(lines.join(`
 `));
 }
+function suspend() {
+  process.stdin.setRawMode(false);
+  process.stdin.pause();
+  process.stdin.removeAllListeners("data");
+  process.stdout.write("\x1B[?25h\x1B[2J\x1B[H");
+}
+function resume(state, onData) {
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.setEncoding("utf8");
+  process.stdout.write("\x1B[?25l");
+  process.stdin.on("data", onData);
+  render(state);
+}
+async function runAction(actionName, template, pr, state, onData) {
+  const context = buildContext(toResolvedPR(pr), pr.category);
+  const cmd = interpolate(template, context);
+  suspend();
+  process.stdout.write(source_default.dim(`
+  running ${actionName} on ${pr.repo}#${pr.number}...
+
+`));
+  try {
+    await executeCommand(cmd);
+    resume(state, onData);
+    return source_default.green(`${actionName}: ${pr.repo}#${pr.number}`);
+  } catch {
+    resume(state, onData);
+    return source_default.red(`${actionName} failed`);
+  }
+}
 async function interactiveMode(result, config) {
   if (result.prs.length === 0) {
     console.log(source_default.green(`
@@ -6791,84 +6836,73 @@ 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.
 `);
     return;
   }
-  process.stdin.setRawMode(true);
-  process.stdin.resume();
-  process.stdin.setEncoding("utf8");
-  process.stdout.write("\x1B[?25l");
-  render(result, selectedIndex, message);
   return new Promise((resolve) => {
-    const cleanup = () => {
-      process.stdin.setRawMode(false);
-      process.stdin.pause();
-      process.stdin.removeAllListeners("data");
-      process.stdout.write("\x1B[?25h\x1B[2J\x1B[H");
-    };
-    process.stdin.on("data", async (key) => {
-      const pr = result.prs[selectedIndex];
+    const onData = async (key) => {
+      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") {
+          suspend();
+          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, onData);
+            state.actionMenu = null;
+          }
+        }
+        render(state);
+        return;
+      }
       switch (key) {
         case "q":
         case "\x03":
-          cleanup();
+          suspend();
           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, onData);
           }
           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, onData);
           }
           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, onData);
           }
           break;
         }
@@ -6877,17 +6911,27 @@ 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);
+    };
+    resume(state, onData);
   });
 }
 
@@ -11009,12 +11053,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.8.0",
 	"description": "PR Queue — see what code reviews need your attention",
 	"type": "module",
 	"bin": {