prdoc

Auto-generate rich PR documentation from git diffs using AI (Gemini, OpenAI, or Claude). Creates PRs, posts detailed markdown comments with mermaid diagrams, and keeps them updated on every push.

What it does

git pushd -u origin feat/my-feature
  ↓
1. Pushes your branch to the remote
  ↓
2. Diffs your branch against base (e.g. main), filters files by your globs
  ↓
3. Sends the diff + repo context to your chosen LLM (Gemini / OpenAI / Claude)
  ↓
4. LLM returns structured JSON: title, summary, file changes, mermaid diagrams, risks
  ↓
5. Assembles a full markdown document with badges, collapsible sections, diagrams
  ↓
6. Creates a PR if none exists → posts the markdown as a PR comment
  ↓
7. On subsequent pushes, updates the same comment with the latest documentation

What the generated PR comment looks like

• Title with badges (branch, base, files changed, added/modified/deleted counts)
• Executive summary (2-4 sentences)
• Mermaid diagrams (sequence, flowchart, ER, state — only when meaningful)
• File changes grouped by status (added/modified/deleted/renamed) in collapsible sections
• Module impact map with cross-module dependency notes
• Testing suggestions
• Risks and breaking changes

Install

npm install -g prdoc-cli

Requires Node.js 20+.

Quick start

# 1. Full interactive setup
prdoc init

# 2. Set your GitHub token (needs `repo` scope)
export GITHUB_TOKEN=ghp_...

# 3. Push and auto-generate PR docs
git pushd -u origin feat/my-branch

That's it. On first push it creates a PR and posts documentation. On subsequent pushes it updates the same comment.

Commands

prdoc init

Full interactive setup. Walks you through:

1. LLM provider — pick Gemini, OpenAI, or Claude
2. API key — enter your key (stored in ~/.prdocrc.json, never committed)
3. Base branch — default target for PRs (e.g. main, develop)
4. Project config — optionally create .prdocrc.json with repo-specific globs
5. git pushd alias — optionally install the git pushd command

prdoc init

If you've already run init, it will ask if you want to reconfigure.

prdoc run

The core command. Generates documentation and posts it to GitHub.

prdoc run [options]

Options:

| Flag | Description | Default | |---|---|---| | --since <commit> | Diff starting point | HEAD~1 (or base branch if PR exists) | | -b, --branch <branch> | Target base branch for PR | from config | | -t, --title <title> | Override auto-generated PR title | LLM-generated | | --dry-run | Write prdoc-preview.md locally, skip GitHub entirely | — | | -y, --yes | Non-interactive mode, skip all prompts | — |

Examples:

# Preview docs locally without touching GitHub
prdoc run --dry-run

# Generate docs for all changes since main
prdoc run --since main

# Generate docs for changes since a specific commit
prdoc run --since abc1234

# Target a different base branch
prdoc run --since develop -b develop

# Override the PR title
prdoc run --since main -t "feat: new payment flow"

# Non-interactive (used by git pushd alias)
prdoc run --yes

Behaviour:

• If no PR exists for the current branch:
  • Interactive mode: asks if you want to create one and which base branch
  • Non-interactive (--yes): creates PR automatically using configured base branch
• If a PR already exists: finds it and updates the documentation comment
• If commentOnExisting: true (default): edits the existing prdoc comment instead of posting a new one
• Retries LLM calls 3 times with backoff on transient errors (503, rate limits, timeouts)
• Retries PR creation 3 times with 5s waits (handles race conditions)

prdoc switch

Change your LLM provider. Remembers API keys for all providers you've configured, so switching back doesn't require re-entering keys.

prdoc switch

Shows current provider, lets you pick a new one, asks for API key only if not already stored.

prdoc status

Shows your current configuration at a glance.

prdoc status

Output:

  prdoc ─ status

  Provider:    Gemini (Google)
  Model:       gemini-2.5-flash
  API key:     ****pgz8
  Base branch: main
  GitHub token:****oatK

  git pushd:   installed (push + auto-generate docs)

  Config: /Users/you/.prdocrc.json

  Commands:
    prdoc run          generate PR docs
    prdoc run --dry-run preview locally
    prdoc switch       change LLM provider
    prdoc init         reconfigure
    git pushd          push + auto-generate docs

git pushd

A git alias installed by prdoc init. Pushes your branch, then runs prdoc automatically.

# Push new branch and generate docs
git pushd -u origin feat/my-feature

# Regular push (branch already tracked)
git pushd

# Push with force
git pushd --force-with-lease

All git push arguments are passed through. After the push succeeds, prdoc run --yes executes automatically.

If you don't want docs for a specific push, just use regular git push.

How it works internally:

git pushd = git push "$@" && npx prdoc-cli run --yes

Supported LLM providers

| Provider | Package | Default model | Env var | Get a key | |---|---|---|---|---| | Gemini (Google) | @google/genai | gemini-2.5-flash | GEMINI_API_KEY | aistudio.google.com/apikey | | OpenAI (GPT) | openai | gpt-4o | OPENAI_API_KEY | platform.openai.com/api-keys | | Claude (Anthropic) | @anthropic-ai/sdk | claude-sonnet-4-20250514 | ANTHROPIC_API_KEY | console.anthropic.com |

Gemini is bundled. OpenAI and Anthropic SDKs are optional dependencies — installed automatically when needed.

You can override the model in ~/.prdocrc.json:

{ "model": "gpt-4-turbo" }

Configuration

prdoc uses two config files:

Global config (~/.prdocrc.json)

Created by prdoc init. Stores secrets and user preferences. Never committed to git.

{
  "provider": "gemini",
  "model": "gemini-2.5-flash",
  "baseBranch": "main",
  "geminiApiKey": "AIza...",
  "openaiApiKey": "sk-...",
  "anthropicApiKey": "sk-ant-..."
}

| Field | Description | |---|---| | provider | Active LLM provider: "gemini", "openai", or "anthropic" | | model | Model to use (defaults per provider if omitted) | | baseBranch | Default PR target branch | | geminiApiKey | Google Gemini API key | | openaiApiKey | OpenAI API key | | anthropicApiKey | Anthropic API key |

Project config (.prdocrc.json in repo root)

Optional. Repo-specific settings that are safe to commit (no secrets).

{
  "baseBranch": "develop",
  "include": ["src/**", "lib/**", "app/**", "*.ts", "*.js", "*.go", "*.py"],
  "exclude": [
    "package-lock.json",
    "yarn.lock",
    "pnpm-lock.yaml",
    "*.min.js",
    "*.min.css",
    "dist/**",
    ".next/**",
    "node_modules/**"
  ],
  "maxDiffLines": 4000,
  "sections": ["summary", "changes", "mermaid", "modules", "testing", "risks"],
  "createPR": true,
  "postComment": true,
  "commentOnExisting": true
}

| Field | Type | Default | Description | |---|---|---|---| | baseBranch | string | "main" | PR target branch (overrides global) | | include | string[] | ["**"] | Glob patterns for files to include in diff | | exclude | string[] | (see above) | Glob patterns for files to exclude | | maxDiffLines | number | 4000 | Truncate diff after this many lines | | sections | string[] | all | Which doc sections to generate | | createPR | boolean | true | Create PR if none exists | | postComment | boolean | true | Post markdown as PR comment | | commentOnExisting | boolean | true | Update existing prdoc comment vs post new |

Available sections: summary, changes, mermaid, modules, testing, risks

Config resolution order

1. Project .prdocrc.json (highest priority for repo settings)
2. Global ~/.prdocrc.json (provider, keys, base branch)
3. Environment variables (fallback for keys and GitHub token)
4. Defaults

You can also add a "prdoc" key to package.json — cosmiconfig picks it up.

Environment variables

| Variable | Description | Required | |---|---|---| | GEMINI_API_KEY | Google Gemini API key | If using Gemini and not in config | | OPENAI_API_KEY | OpenAI API key | If using OpenAI and not in config | | ANTHROPIC_API_KEY | Anthropic API key | If using Claude and not in config | | GITHUB_TOKEN | GitHub PAT with repo scope | Yes, for PR creation/comments |

Environment variables override config file values.

Generated doc sections

| Section | What it contains | |---|---| | Summary | 2-4 sentence executive summary of what changed and why | | Diagrams | Mermaid diagrams (sequence, flowchart, ER, state) — only when meaningful | | File changes | Per-file descriptions grouped by status, in collapsible <details> blocks | | Module impact | Which modules are affected and cross-module dependency notes | | Testing | Suggested test coverage or what to verify manually | | Risks | Breaking changes, migration steps, or areas of concern |

Error handling

• LLM errors (503, rate limits, timeouts): retries 3 times with increasing backoff, then shows a clean error message with the reason and a command to retry
• PR creation errors (branch not on remote yet): retries 3 times with 5s waits
• Network errors: detected and reported clearly
• Invalid API key: tells you to run prdoc switch
• No changes found: exits gracefully with a message

Tips & recipes

Large monorepos — scope to your service:

{ "include": ["services/payments/**", "shared/types/**"] }

Different base branch per repo:

{ "baseBranch": "develop" }

Disable PR creation (just post comment on existing PRs):

{ "createPR": false, "postComment": true }

Skip diagrams for faster generation:

{ "sections": ["summary", "changes", "modules", "risks"] }

Preview before posting:

prdoc run --since main --dry-run
cat prdoc-preview.md

Document a range of commits:

prdoc run --since v1.2.0

Use in CI (non-interactive):

- run: prdoc run --yes --since ${{ github.event.pull_request.base.sha }}

Switch models: Edit ~/.prdocrc.json and change "model":

{ "provider": "openai", "model": "gpt-4-turbo" }

Uninstall

# Remove the package
npm uninstall -g prdoc-cli

# Remove the git alias
git config --global --unset alias.pushd

# Remove global config
rm ~/.prdocrc.json

# Remove project config (if created)
rm .prdocrc.json

License

MIT