@nvice-r/pr-commands

Provider-agnostic pull-request helper for Claude Code. One /pr command that drafts a PR title + body in your team's convention, infers the base branch, warns on oversized diffs, attaches reviewers, and creates the PR — with the provider (Bitbucket / GitHub / GitLab) auto-detected from your git remote.

Status: macOS + Bitbucket today. GitHub / GitLab and Linux are stubbed and land without new command files — see Architecture.

Install

npx @nvice-r/pr-commands

The interactive wizard:

1. Environment — detects OS → token source (macOS keychain).
2. Work directory — the repo to configure. Prompted with the current dir pre-filled and editable (or pass --dir). Must be a git repo.
3. Provider — detected from git remote get-url origin.
4. Identity + token — reads your API token from the keychain (or tells you how to add one).
5. Reviewers — fetches the repo's default reviewers into an interactive checklist (↑/↓ move · space toggle · a all · n none · b back · enter confirm; all pre-selected).
6. Convention — pick a preset, then review/edit its title-pattern, ticket-regex, and template-sections (each pre-filled from the preset, editable). A placeholder legend (<ver>, <desc>, <ticket>, …) is shown. Concrete values are written to config — /pr reads those, not a hard-coded table.
7. Install — writes config + roster, drops the binaries and the /pr skill.

Every prompt is reversible: in a list press b to step back; in a text field, append :b to the value and press enter (the field is pre-filled, so :b at the end triggers back). Back navigation is field-level (you can revisit any single convention field).

Flags:

| flag | effect | |------|--------| | --dir <path> | repo to configure (default: cwd) | | --provider <p> | force bitbucket|github|gitlab instead of detecting | | --all | install every ready provider binary, not just the detected one | | --yes | non-interactive: reviewers = all, convention = trueid | | --dry-run | print planned actions, write nothing | | --help | usage |

Dry-run first to see exactly what will be written:

npx @nvice-r/pr-commands --dry-run --dir /path/to/repo

Prerequisites

• Node ≥ 16 (for the installer only; the installed tools are bash).
• ~/.local/bin on your PATH. The installer warns if it isn't:

  export PATH="$HOME/.local/bin:$PATH"

• A Bitbucket API token in the keychain (the installer can't mint secrets):

  security add-generic-password -s bitbucket-api-token -a [email protected] -w '<api-token>'

  Without it, install still completes but reviewers aren't auto-fetched.

What gets installed

Everything is global — nothing lands in a repo's .claude/, so it works identically from every clone and every git worktree, no symlinks.

| Artifact | Path | |----------|------| | Shared library | ~/.local/bin/pr-common.sh | | Provider binary | ~/.local/bin/bbpr (ghpr/glpr later) | | Config | ~/.config/pr/config | | Reviewer roster | <main-repo-root>/<agent_dir>/pr-reviewers.txt (default .claude; shared across worktrees) | | /pr skill | ~/.claude/commands/pr.md |

Usage

In Claude Code, from any configured repo:

/pr                 # infer base, draft PR, confirm, create
/pr feature/2.3.0/center   # explicit base branch
/pr draft           # create as draft
/pr help            # help

/pr gathers git context, proposes a title + body in your convention, shows it for confirmation, then calls the detected binary. It never creates a PR silently.

Configuration

~/.config/pr/config (written by the installer):

os=macos             # macos | linux
token_src=keychain   # keychain | secret-tool | env
[email protected]
convention=trueid    # see presets

Edit by hand any time. A missing config is a hard error — /pr and the binaries refuse to guess. Re-run the installer to regenerate.

Convention presets

| preset | title pattern | ticket regex | template sections | |--------|---------------|--------------|-------------------| | trueid | [<ver>] Feature/<ver>/SC-XXXX <desc> | SC-\d+ | What Happened / Insight / Proof of Work | | conventional | <type>(<scope>): <desc> | [A-Z]+-\d+ | Summary / Changes / Testing | | github-default | <desc> (#<issue>) | #\d+ | Summary / Test plan | | custom | your title_pattern= | your ticket_regex= | your template_sections= (pipe-separated) |

custom example:

convention=custom
title_pattern=<ticket>: <desc>
ticket_regex=JIRA-\d+
template_sections=Context|Changes|Risk

Reviewers

Roster lives in the agent folder under the main repo root (agent_dir in config, default .claude), so it's editable next to the code. Resolved via git --git-common-dir/.., so all worktrees of a repo share one roster:

<main-repo-root>/.claude/pr-reviewers.txt        # or <agent_dir>/… — .cursor, .aider, …

You (the author) are excluded on install — bbpr also drops self at PR time. One entry per line, trailing # Name comment optional:

{01234567-89ab-cdef-0123-456789abcdef}  # Alice
{fedcba98-7654-3210-fedc-ba9876543210}  # Bob

It's plain data — edit freely, no reinstall. Consider gitignoring it unless the team wants the roster committed. Load order: $BBPR_REVIEWERS → <agent_dir>/pr-reviewers.txt → root .pr-reviewers.txt (pre-0.1.1) → global ~/.config/pr/reviewers/<ws>-<slug>.txt → legacy. Run-time overrides: --no-reviewers skips all, --reviewer <uuid> appends.

Auth precedence (email)

--email flag → $BB_EMAIL → git config bbpr.email → config email → keychain account. The token is always read from the keychain (or $PR_TOKEN when token_src=env).

Provider support

| provider | binary | status | |----------|--------|--------| | Bitbucket Cloud | bbpr | ✅ ready | | GitHub | ghpr | 🚧 stub — errors not-yet-supported | | GitLab | glpr | 🚧 stub |

| OS | token source | status | |----|--------------|--------| | macOS | keychain | ✅ ready | | Linux | secret-tool / $PR_TOKEN | 🚧 present, untested |

Architecture

• Split by provider, not by OS. Each provider gets its own small binary (bbpr/ghpr/glpr) because the REST APIs genuinely differ. OS differences (token retrieval) are a single get_token() function switched by uname, not a separate binary. Ceiling: 3 binaries, never 3 × OS.
• Shared logic in pr-common.sh — git scan, base save, reviewer load, arg parse, token — sourced by every binary. A provider binary is ~40 lines: payload shape + endpoint + parse.
• One generic /pr skill. Convention lives in config, not the skill, so the skill is provider- and team-neutral and installs globally. Adding a provider = one binary + one dispatch line, zero new skill files.

Full rationale in DECISIONS.md.

Troubleshooting

| symptom | fix | |---------|-----| | no ~/.config/pr/config | run npx @nvice-r/pr-commands | | reviewers not fetched | add the keychain token (see Prerequisites), re-run | | WARN ~/.local/bin not on PATH | add the export line above to your shell rc | | not-yet-supported: <provider> | GitHub/GitLab aren't implemented yet | | worktree runs old behavior | nothing is repo-local here; ensure pr.md is at ~/.claude/commands/pr.md, not a stale repo copy |

Uninstall

rm ~/.local/bin/bbpr ~/.local/bin/pr-common.sh
rm -rf ~/.config/pr
rm ~/.claude/commands/pr.md
# roster lives in each repo — remove per repo if wanted:
rm <main-repo-root>/.claude/pr-reviewers.txt

Development

install.js          npx entry (wizard)
assets/bin/*        provider binaries + shared lib (source of truth; copied on install)
assets/skill/pr.md  generic /pr skill (source of truth; copied on install)

assets/ is the single source of truth — both the installer (install.js) and the published package (files in package.json) read from it. No duplicate tree to keep in sync.

Publish (owner only):

npm login
npm publish --access public

License

MIT © nvice.r