Build a Git Commit-Message Generator with Claude: End-to-End prepare-commit-msg Hook Tutorial

Image: git/git on GitHub, used for editorial coverage of the canonical Git source and its prepare-commit-msg hook.

What you’ll build

A small Python project where every time you run git commit, a hook reads your staged diff, sends it to Claude, and pre-fills the commit-message editor with a Conventional Commits draft (feat(api): add retry on 429 with exponential backoff). You edit, save, and ship — or quit the editor to abort, same as today. An environment-variable opt-out skips the hook for a single commit, and a hard fallback writes a plain template when the Anthropic API is unreachable so a flaky network never blocks a commit. The whole project fits in roughly 120 lines of Python plus a one-line shell shim.

Per the Git documentation, the prepare-commit-msg hook runs after the default message is prepared but before the editor opens, receives the message file path as its first argument, and can rewrite the file in place — exit code zero proceeds, non-zero aborts the commit. ¹ The Conventional Commits 1.0.0 specification defines the structured format Claude will draft against: <type>(<scope>): <description> on the first line, with types like feat, fix, docs, refactor, test, chore, and an optional body separated by a blank line. ² Claude Haiku 4.5 is the right register for this task — small input (a diff and a short prompt), short output (one to five lines), latency in the few-hundred-millisecond band — and is billed at $1 per million input tokens and $5 per million output tokens per the Anthropic pricing page, ³ well under a tenth of a cent per commit for typical diff sizes.

The differentiator over generic “AI commit message” tools is the opt-out and the fallback: the hook never blocks a commit, never leaks secrets to the API, and gets out of the way the moment you don’t want it.

Prerequisites

You’ll need:

• Python 3.10 or newer.
• Git 2.39 or newer (any modern install).
• An Anthropic API key. Set it once in your shell:

export ANTHROPIC_API_KEY="sk-ant-..."

The Anthropic Python SDK reads ANTHROPIC_API_KEY from the environment when you instantiate Anthropic() with no arguments, per the SDK’s PyPI page. ⁴

• A Git repository to test in. A throwaway clone of any project works.

Step 1: Install the SDK

Create a virtual environment somewhere stable — the hook will reference its Python interpreter by absolute path — and install the Anthropic SDK:

mkdir -p ~/.local/share/claude-commit-hook
cd ~/.local/share/claude-commit-hook
python -m venv .venv
source .venv/bin/activate
pip install anthropic

The anthropic package on PyPI ships the official Python client; instantiating Anthropic() without arguments reads the API key from the environment per the SDK documentation. ⁴

Image: Anthropic — Claude Haiku 4.5 announcement, used for editorial coverage of the model the hook invokes.

Step 2: Read the staged diff from Python

The hook needs to know what’s being committed. git diff --cached (also spelled --staged) prints the diff of what’s about to be committed against HEAD, per the git-diff reference. ⁵ Save the following to ~/.local/share/claude-commit-hook/generate.py:

import os
import subprocess
import sys
from pathlib import Path

MAX_DIFF_CHARS = 12000  # ~3,000 tokens; trims very large diffs

def staged_diff() -> str:
    """Return the staged diff, or empty string if nothing is staged."""
    result = subprocess.run(
        ["git", "diff", "--cached", "--no-color", "--minimal"],
        capture_output=True,
        text=True,
        check=False,
    )
    if result.returncode != 0:
        return ""
    return result.stdout[:MAX_DIFF_CHARS]

Three details earn their place. --no-color strips ANSI escape codes that would otherwise leak into the prompt. --minimal asks Git for the smallest diff representation, which both shrinks the token bill and gives Claude a cleaner picture of what changed. The MAX_DIFF_CHARS ceiling caps prompt size so a one-off 50-file refactor doesn’t blow through the context window or produce a generic summary — beyond roughly 3,000 tokens of diff, the model loses the per-file detail that makes commit messages useful.

Step 3: Ask Claude for a Conventional Commits draft

Add the call to Claude. The prompt is short and structured: it tells the model the format, gives it the diff, and asks for the message with no extra prose.

from anthropic import Anthropic, APIError

SYSTEM_PROMPT = """You write Conventional Commits messages.

Format: <type>(<scope>): <description>
- type is one of: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
- scope is optional, lowercase, one word (the affected module or area)
- description is imperative present tense, lowercase, no trailing period, max 72 chars
- Optional body after a blank line: 1-3 short lines explaining the why, wrapped at 72 chars
- Output ONLY the commit message. No preamble, no code fences, no quotes."""

USER_TEMPLATE = """Write a Conventional Commits message for this staged diff:

```diff
{diff}
```"""

def generate_message(diff: str, timeout_s: float = 8.0) -> str:
    """Call Claude Haiku 4.5 and return the suggested commit message."""
    client = Anthropic(timeout=timeout_s)
    response = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=200,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": USER_TEMPLATE.format(diff=diff)}],
    )
    return response.content[0].text.strip()

The claude-haiku-4-5 model ID resolves to the current Claude Haiku 4.5 release per the Anthropic models overview page; ⁶ it’s the cheapest tier that reliably produces structured output and the latency floor matters when this runs between you typing git commit and the editor opening. The timeout=8.0 passed to the SDK client comes from the SDK’s documented client-level timeout argument ⁴ — eight seconds is generous for Haiku and short enough that a hung connection doesn’t make the hook feel broken. max_tokens=200 is more than any conforming commit message needs and cheap enough not to matter.

Step 4: Add the opt-out flag and the fallback

This is the part most “AI commit” tools skip, and it’s the part that makes the hook safe to leave on by default. The user opens generate.py and adds the entrypoint:

def fallback_message() -> str:
    """Plain template used when the API is unreachable or opted out."""
    return "chore: update\n\n# (claude-commit-hook offline: edit this message)"

def main(commit_msg_path: str, commit_source: str = "") -> int:
    # Skip when Git already provided a message (merge, squash, -m, -F, template)
    if commit_source in {"message", "template", "merge", "squash", "commit"}:
        return 0
    # Honour the opt-out env var
    if os.environ.get("CLAUDE_COMMIT_HOOK") == "off":
        return 0
    # Require an API key; otherwise fall back silently
    if not os.environ.get("ANTHROPIC_API_KEY"):
        return 0

    diff = staged_diff()
    if not diff.strip():
        return 0  # nothing staged; let Git handle it

    try:
        message = generate_message(diff)
    except (APIError, OSError, TimeoutError):
        message = fallback_message()

    # Preserve any existing user content (e.g. -m flag or template) below
    path = Path(commit_msg_path)
    existing = path.read_text(encoding="utf-8")
    path.write_text(message + "\n\n" + existing, encoding="utf-8")
    return 0

if __name__ == "__main__":
    msg_path = sys.argv[1]
    source = sys.argv[2] if len(sys.argv) > 2 else ""
    sys.exit(main(msg_path, source))

Four guards earn their place. The commit_source check honours Git’s documented hook contract — the prepare-commit-msg hook receives a second argument naming the message source (message, template, merge, squash, commit), and the githooks reference notes the hook should generally skip those cases. ¹ The CLAUDE_COMMIT_HOOK=off env-var check is the per-commit opt-out: CLAUDE_COMMIT_HOOK=off git commit skips the hook entirely without disabling it permanently. The missing-API-key check makes the hook a silent no-op on any machine where the key isn’t set — useful for shared developer environments. The try / except around generate_message catches network errors, timeouts, and any documented Anthropic API errors per the SDK’s errors reference, ⁷ and writes a plain chore: update template so a flaky network never blocks a commit.

Image: Anthropic — API landing page, used for editorial coverage of the Messages API endpoint the hook calls.

Step 5: Wire it up as a prepare-commit-msg hook

Git looks for hooks in .git/hooks/ by default, but per the git-config reference, setting core.hooksPath lets you point every repository at a single shared directory. ⁸ Use that — it means you install the hook once and it applies to every clone on the machine.

Create the shared hooks directory and the shim:

mkdir -p ~/.config/git/hooks
cat > ~/.config/git/hooks/prepare-commit-msg <<'EOF'
#!/usr/bin/env bash
exec ~/.local/share/claude-commit-hook/.venv/bin/python \
  ~/.local/share/claude-commit-hook/generate.py "$@"
EOF
chmod +x ~/.config/git/hooks/prepare-commit-msg

Then tell Git to use the directory globally:

git config --global core.hooksPath ~/.config/git/hooks

The exec builtin replaces the shell with the Python interpreter so process accounting reflects one process, not two. The absolute path to the venv’s Python is what makes the hook self-contained — no source activate step, no PATH dependency. "$@" forwards all arguments Git passes to the hook (message file path, message source, optional SHA) through to the Python script unchanged, matching the argument list documented in the githooks reference. ¹

Image: GitHub Docs — Get started, used for editorial coverage of the Git fundamentals the hook layers onto.

Step 6: Try it

Stage a real change in any repository — edit a file, then run git add — and commit:

git commit

Your editor opens with the generated message at the top. Edit it like any commit message, save, exit. The commit lands. To skip the hook for one commit (when you genuinely just want wip and don’t want to pay the API call):

CLAUDE_COMMIT_HOOK=off git commit -m "wip"

To turn the hook off entirely on one machine, unset ANTHROPIC_API_KEY from your shell profile — the hook becomes a silent no-op. To uninstall, run git config --global --unset core.hooksPath and delete the two directories.

Image: GitHub Docs — Using Git, used for editorial coverage of the commit workflow this hook plugs into.

Common failure modes worth knowing

A few sharp edges show up once the hook is part of the muscle memory.

Large diffs produce generic messages. The 12,000-character cap in Step 2 is a floor under quality, not a ceiling on commit size. Per the git-commit reference, large refactors are often better split into multiple commits anyway, ⁹ and the hook quietly nudges you in that direction by getting vaguer the bigger the diff gets.

Secrets in diffs. If you accidentally stage a .env file or hard-coded credential, the hook sends it to the Anthropic API as part of the diff prompt. The right defence is upstream: a pre-commit hook (a separate hook that runs before prepare-commit-msg) that scans for secrets and aborts the commit on a hit. Tools like gitleaks and detect-secrets fill that slot.

The model occasionally outputs code fences or quotes. The system prompt explicitly forbids them, but Haiku 4.5 sometimes wraps output anyway. A two-line strip in generate_message handles it — match the leading ``` and the trailing ```, strip them, return the inner text. Worth adding once you hit it.

Commits via -m or -F skip the hook. The commit_source guard in Step 4 deliberately bails on those because the user already passed a message. If you want Claude to always run, drop the "message" entry from the skip set — but then git commit -m "wip" becomes a paid API call.

Where to take it next

A few extensions are one short addition each:

• Caching. Hash the diff with hashlib.sha1 and cache the generated message in ~/.cache/claude-commit-hook/. Re-runs on the same staged diff (rebasing, amending) skip the API call.
• Custom scope vocabulary. Pass your repository’s module list in the system prompt so Claude picks scopes that match your actual codebase (feat(billing): rather than feat(api):).
• Body templates. Per the Conventional Commits 1.0.0 spec, the optional body supports BREAKING CHANGE: footers for major version bumps; ² extend the system prompt to surface breaking-change signals when the diff removes a public function or changes a function signature.
• Repo-local override. Layer a .git/hooks/prepare-commit-msg in specific repositories to override the global hook with a project-specific prompt. Git’s hook resolution picks the per-repo path when core.hooksPath isn’t set in that repo’s config. ⁸

The bones — read the staged diff, draft against Conventional Commits, opt out cleanly, fall back honestly — are all here. Everything else is shading.