Skip to main content

suggestion-bot

Build npm version

suggestion-bot submits code reviews with suggestions based on your diffs.

screenshot of code review with suggestions

Usage​

Usage: cli.js [options] [diff | file]

Submit code reviews with suggestions based on your diffs

Arguments:
  diff | file            the diff or file containing diff to create suggestions from

Options:
  -h, --help             display this help message
  -v, --version          display version number
  -m, --message <msg>    use the specified message as the PR comment
  -f, --fail             fail if comments could not be posted

Examples:
  # Submit current changes as suggestions
  GITHUB_TOKEN=<secret> suggestion-bot "$(git diff)"

  # Alternatively, pipe to suggestion-bot
  # to avoid escape character issues
  git diff | GITHUB_TOKEN=<secret> suggestion-bot

If your CI is hosted by Azure DevOps, replace GITHUB_TOKEN with AZURE_PERSONAL_ACCESS_TOKEN.

Requirements​

  • Host your code on GitHub
  • GITHUB_TOKEN permissions:
    • pull-requests: write — required for creating code reviews
    • issues: write — fallback in case creating a review fails

-- or --

Recipes​

Using suggestion-bot with GitHub Actions​

  1. Install suggestion-bot in your project

    yarn add suggestion-bot --dev

  2. Configure your GitHub workflow so suggestion-bot can access the GITHUB_TOKEN secret provided by GitHub via an environment variable with the same name:

    # .github/workflows/build.yml
    jobs:
      lint:
        runs-on: ubuntu-latest
        steps:
          - name: Set up Node.js
            uses: actions/setup-node@v6
            with:
              node-version: 24
          - name: Checkout
            uses: actions/checkout@v6
          - name: Install
            run: yarn
          - name: ClangFormat
            if: ${{ github.event_name == 'pull_request' }}
            env:
              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
            run: scripts/clang-format-diff.sh | yarn suggestion-bot

Using suggestion-bot with clang-format​

Use clang-format-diff to format only changed files:

curl --silent --show-error --remote-name https://raw.githubusercontent.com/llvm/llvm-project/release/10.x/clang/tools/clang-format/clang-format-diff.py
git diff --unified=0 --no-color @^ \
  | python clang-format-diff.py -p1 -regex '.*\.(cpp|cc|c\+\+|cxx|c|cl|h|hh|hpp|m|mm|inc)' -sort-includes \
  | yarn suggestion-bot

Using suggestion-bot with Prettier​

We must first write a script that pipes Prettier's output to diff so we can feed it to suggestion-bot later.

#!/usr/bin/env node

import { spawnSync } from "node:child_process";
import * as fs from "node:fs";
import * as prettier from "prettier";
import suggest from "suggestion-bot";

const diff = process.argv.slice(2).reduce((diff, filepath) => {
  const source = fs.readFileSync(filepath, { encoding: "utf8" });
  const { stdout } = spawnSync("diff", ["--unified", filepath, "-"], {
    input: prettier.format(source, { filepath }),
    encoding: "utf-8",
  });
  return diff + stdout;
}, "");

suggest(diff);

Save the script somewhere, e.g. scripts/prettier-diff.mjs, then invoke it with Node:

node scripts/prettier-diff.mjs $(git ls-files '*.js')