PR Title Conventional Commit Reminder - Claude Code Hook

Overview

This hook gives a final local reminder before a Claude Code session stops: is the current PR title ready for release tooling?

It uses Conventional Commits as the default title shape, including the repository-specific content type used by this directory's content PR workflow. When gh is installed and authenticated, the hook reads the current branch's PR title with gh pr view. When no PR is available, it falls back to the latest commit subject so a contributor still gets a useful reminder before pushing or opening a PR.

Features

• Checks the current GitHub PR title at session stop, after Claude has finished editing and before a human is likely to open or update a PR.
• Falls back to the latest commit subject when GitHub CLI is missing, unauthenticated, offline, or the current branch has no PR.
• Accepts common Conventional Commits types plus content by default: build, chore, ci, content, docs, feat, fix, perf, refactor, revert, style, and test.
• Supports custom type policy with PR_TITLE_CONVENTIONAL_TYPES, using either a pipe-separated or comma-separated list.
• Stays advisory by default and can be made blocking only with the explicit PR_TITLE_REMINDER_STRICT=1 opt-in.

How It Works

On Stop, the hook confirms it is running inside a git work tree and skips default branches such as main, master, and trunk unless PR_TITLE_REMINDER_CHECK_DEFAULT=1 is set.

For feature branches, it first tries a read-only gh pr view --json title,url,headRefName. If a PR title is found, the title must match:

type(scope): summary

The scope is optional and a breaking-change bang is allowed, so feat!: remove legacy endpoint and fix(api): handle empty cursor both pass. If no PR title is available, the same check runs against git log -1 --pretty=%s.

Use Cases

• Keep squash-merge PR titles release-note ready in repositories that generate changelogs or release notes from merge commit subjects.
• Nudge Claude to update a vague title such as updates before the contributor requests review.
• Support content repositories whose PR titles use a custom type like content(hooks): add package policy hook.
• Keep the reminder local and lightweight instead of adding a repository-wide required check.

Installation

1. Create the hooks directory: mkdir -p .claude/hooks
2. Create the hook file: touch .claude/hooks/pr-title-conventional-commit-reminder.sh
3. Paste the script body into that file and make it executable: chmod +x .claude/hooks/pr-title-conventional-commit-reminder.sh
4. Add the configuration below to .claude/settings.json for a project hook or ~/.claude/settings.json for a user hook.
5. Authenticate GitHub CLI with gh auth login if you want PR-title lookup.

Hook Configuration

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pr-title-conventional-commit-reminder.sh"
          }
        ]
      }
    ]
  }
}

Configuration

• PR_TITLE_CONVENTIONAL_TYPES - allowed type names, separated by | or ,. Defaults to build|chore|ci|content|docs|feat|fix|perf|refactor|revert|style|test.
• PR_TITLE_REMINDER_STRICT=1 - exit 2 on a mismatch. Leave unset for the default advisory behavior.
• PR_TITLE_REMINDER_OFFLINE=1 - skip GitHub CLI lookup and check only the latest commit subject.
• PR_TITLE_REMINDER_CHECK_DEFAULT=1 - check main, master, or trunk instead of skipping default branches.

Limitations

• The hook checks title shape, not whether the title accurately describes the diff.
• GitHub CLI looks up the PR for the current branch, so forks, renamed remotes, or multiple matching PRs can require normal gh configuration first.
• Custom scopes are treated syntactically; the hook does not know whether api, docs, or hooks are approved scopes for a repository.
• Strict mode can interrupt a stop workflow, so enable it only after the team agrees on title policy and false-positive handling.

Related Content Fit

This entry is intentionally narrower than the existing git-smart-commit command, git pre-commit validator hook, Husky commit governance skill, and contributor commit/changelog rules. Those entries help create or review commits and release policy. This hook adds a session-end runtime reminder focused on the current PR title, with explicit GitHub CLI network/account disclosure and an offline fallback.

Source and References

• Conventional Commits 1.0.0: https://www.conventionalcommits.org/en/v1.0.0/
• Conventional Commits source repository: https://github.com/conventional-commits/conventionalcommits.org
• GitHub CLI gh pr view manual: https://cli.github.com/manual/gh_pr_view
• GitHub Docs: About merge methods on GitHub: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github
• Claude Code hooks documentation: https://code.claude.com/docs/en/hooks

• Source repositorygithub.com 2026-07-20T09:33:29+00:00
• Documentationconventionalcommits.org
• Submitted by MkDev112026-06-05