Build an AI Git Commit Message Generator: Full Tutorial

An AI git commit message generator is the smallest possible piece of agentic developer tooling — and one of the highest-leverage. This tutorial walks through a 200-line Node CLI that reads your staged diff, sends it to Claude Haiku 4.5 with a tight system prompt, and produces a Conventional Commits message with accept, edit, or reject UX baked in.

The stakes are higher than they look. Commit messages are eternal— the one piece of engineering work that survives long after the code it describes is refactored, replaced, or deleted. Yet they're the line item engineers rush most. A small, sharp AI tool wired into your pre-commit hook turns the rushed two-second decision into a structured, reviewable artifact at sub-second latency for less than a tenth of a cent per commit.

This guide covers the full build: package layout, prompt design with anti-hallucination rules, large-diff handling and secret redaction, the interactive CLI flow, husky installation, and a GitHub Actions workflow that lints commit history on every PR. Everything is paste-ready, opinionated on defaults, and reversible in under a minute.

Every engineer who has bisected a production bug to a 2018 commit titled fix stuff understands the cost of poor commit history. Git history is the only audit trail of intent that survives the code itself — refactors come and go, but the commit log is forever. It powers code archaeology, release notes, security audits, git blame investigations, and the autogenerated changelogs that downstream consumers actually read.

Conventional Commits — the type(scope): subject convention — is the de facto standard for making that history machine-readable. It enables automated semver bumping, changelog generation, release-note scaffolding, and PR-time linting. Adopting it costs almost nothing; the friction is purely in the discipline of writing the message in the right shape every time, especially at 5:47 pm on a Friday when you just want to push and go home.

AI augmentation is the right fix here for three reasons. First, the input — a unified diff — is small and structured, exactly the kind of payload a fast model handles well. Second, the output is constrained: a fixed-grammar string, not free-form prose. Third, the task happens at a moment of high cognitive load (the engineer is context-switching out of the work) where a generated draft is almost always better than a rushed first pass. Accept-edit-reject UX preserves human authority while removing the blank-page penalty.

The whole tool is one file. Three runtime dependencies, zero build step, single binary entry. The fewer moving parts a developer-tool CLI has, the faster a team adopts it — every extra config file is a line of resistance.

Initialize the package and install the SDK plus two CLI helpers. commander handles argv parsing and prompts handles the interactive accept-edit-reject flow. @anthropic-ai/sdk is the official Anthropic client — typed, streaming-capable, and honest about error shapes.

The shape of package.json matters because the bin entry is what makes the CLI feel like a first- class tool rather than a script. Wire it like this:

{
  "name": "@you/commit-ai",
  "version": "0.1.0",
  "type": "module",
  "bin": {
    "commit-ai": "./src/index.js"
  },
  "engines": { "node": ">=22" },
  "dependencies": {
    "@anthropic-ai/sdk": "^0.40.0",
    "commander": "^14.0.0",
    "prompts": "^2.4.2"
  }
}

Run pnpm link --global once during development and commit-ai is on your PATH. For team adoption, publish to your internal registry or vendor the tool into a monorepo workspace and reference the binary via pnpm exec commit-ai.

The model receives two things and only two things: a static system prompt that defines the output contract, and the user-message payload containing the unified diff from git diff --staged. Nothing else. No PR title, no issue number, no branch name, no readme excerpt. Adding context here sounds helpful and is actually corrosive — the model starts blending descriptions instead of summarizing the actual change.

Force structured JSON output. The output schema has four fields: type (an enum from the Conventional Commits spec), scope (optional, a single kebab-case token), subject (≤72 chars, imperative mood, no trailing period), and body(optional, wrapped at 72 chars, used for the "why"). JSON mode means parsing reduces to JSON.parse and validation is a 20-line Zod schema — no regex acrobatics.

A working system prompt — copy it, tune the type enum to your team's conventions, ship it:

You write Conventional Commits messages from staged git diffs.

OUTPUT: JSON only, matching the schema:
{
  "type": "feat" | "fix" | "docs" | "style" | "refactor" |
          "perf" | "test" | "build" | "ci" | "chore" | "revert",
  "scope": string | null,
  "subject": string,
  "body": string | null
}

RULES:
- subject: imperative mood, lowercase first letter, no trailing period, <= 72 chars.
- body: optional, wrap lines at 72 chars, explain the WHY not the WHAT.
- scope: derive from the diff's file paths only. If you cannot derive scope
  from the file paths, set it to null. NEVER invent a scope token.
- type: pick the single best match. Multi-purpose diffs default to "refactor".
- No preambles, no apologies, no commentary outside the JSON.

The Anthropic SDK call is correspondingly small. Set model: "claude-haiku-4-5", max_tokens: 512 (commit messages never exceed it), temperature 0.2 for stability, and pass the system prompt via the top-level system field rather than as a user message. Structured output is enforced via the response_formatparameter when the SDK exposes it; if not, append "Return JSON only." to the user message and validate post-parse.

Most staged diffs are small — a hundred lines, two files. A working CLI must also handle the diff that arrives with thirty migrations, a regenerated lockfile, and a vendored SDK update. Three concerns: token budget, secret leakage, and how to summarize the diff that won't fit even in Haiku's generous context window.

Redaction comes first. Run the raw diff through a regex sweep for common secret patterns before sending it to any model: AWS keys (AKIA[0-9A-Z]{16}), Stripe live keys (sk_live_), Slack tokens, GitHub PATs, hex-encoded JWT bodies. Replace each match with <REDACTED:aws-access-key> markers — the model still understands a key was changed without seeing the value. This is non-negotiable in any team where the tool runs against production code.

Token estimation is approximate — a 4-chars-per-token rule of thumb is fine for budgeting. Wrap the model call in a token-counter helper that decides between the three strategies above. The decision logic is roughly twenty lines; don't overengineer it.

One additional rail worth wiring in: skip the diff entirely for commits that are exclusively binary or lockfile changes. If git diff --staged --name-only returns only *.lock, *.png, package-lock.json, generate the message deterministically — chore: update lockfile or chore: add assets — and skip the API call. Saves tokens and avoids the model staring at a 40k-line lockfile diff and inventing meaning.

The interactive loop is where a useful tool becomes a tool the team actually keeps installed. Three keystrokes, no mouse, sub-second response. Anything slower or more clicky than that and engineers will bypass it on every push.

Stream the model output as it generates so the user sees progress — even though the message itself is small, the perceptual latency is what matters. Render the parsed Conventional Commits line in uppercase color (orange for feat, blue for fix, dim for chore), then drop into a single prompts.select with three options pre-bound to hotkeys a, e, r.

Exit codes matter because husky's commit-msg hook respects them. Exit 0 and the commit proceeds; exit non-zero and git aborts. The CLI must also write the generated message to the file path that git passes as argv[2] when invoked from the hook context. A three-line conditional handles both modes:

const msgFile = process.argv[2]; // set by husky/git
if (msgFile && fs.existsSync(msgFile)) {
  fs.writeFileSync(msgFile, formatted);
} else {
  process.stdout.write(formatted + '\n');
}

Two more UX rails worth adding before you call it done. First, --auto-acceptskips the interactive prompt entirely (useful for scripted commits and CI flows where there's no terminal). Second, --dry-run generates and prints the message but never writes or commits — perfect for benchmarking against your real history before you let the tool touch a real commit.

Two installation patterns. Pick one based on how aggressive your team wants to be about adoption. Manual use leaves the tool as an opt-in command an engineer types when they want a draft. Husky use wires it into every commit, with reject-to-bail as the safety valve.

Pattern A — manual

Install globally and call it when you want help. No git hooks touched, no team buy-in required, no surprises.

pnpm add -g @you/commit-ai

# stage changes, then:
git add .
commit-ai            # generates, prompts, writes the message

Pattern B — husky commit-msg hook

The hook intercepts every commit and offers a generated message. If the user typed a message via git commit -m, the hook sees it and exits 0 (don't overwrite an intentional message). If no message was supplied (e.g. plain git commit), the hook generates one.

# one-time setup in the repo
pnpm add -D husky
pnpm dlx husky init

# .husky/commit-msg (one file, three lines)
#!/usr/bin/env sh
[ -s "$1" ] && head -c1 "$1" | grep -qv '^#' && exit 0
commit-ai "$1"

Configuration file

A small .commit-ai.json at the repo root lets each team tune defaults without forking the tool:

{
  "model": "claude-haiku-4-5",
  "style": "conventional-commits",
  "branchScope": {
    "feat/payments-*": "payments",
    "fix/auth-*": "auth"
  },
  "redactionPatterns": ["custom-secret-regex-here"],
  "maxTokens": 512
}

The branchScope map is a small quality-of-life win: when the engineer is on feat/payments-checkout, the tool injects paymentsas a default scope hint into the user message, biasing the model toward the correct scope without forcing it. The anti-hallucination rule in the system prompt still applies — if the diff doesn't actually touch the payments/ path, scope falls back to null.

Uninstall

Reversibility matters. The whole tool comes out cleanly in three commands — keep this in your README so adopters trust the off- ramp:

rm .husky/commit-msg
pnpm remove @you/commit-ai
rm .commit-ai.json

Local hooks are honor-system — engineers can always git commit --no-verify. CI is the enforcement layer. Reuse the same CLI in a GitHub Actions workflow to lint the commit history of every PR, with three modes ranging from advisory to prescriptive.

The workflow shape is straightforward — checkout the PR branch with fetch-depth: 0, walk git log ${{ github.event.pull_request.base.sha }}..HEAD, and run the validation. The Anthropic API key lives in organization secrets and is passed via env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} only for the suggest and auto-fix modes (lint mode needs no API key).

# .github/workflows/commit-lint.yml
name: Commit lint
on: pull_request

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with: { fetch-depth: 0 }
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v5
        with: { node-version: 22 }
      - run: pnpm install --frozen-lockfile
      - name: Validate commit history
        run: pnpm exec commit-ai lint \
             --base ${{ github.event.pull_request.base.sha }}
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

The comment-back bot pattern uses the GitHub REST API via @octokit/rest or the bundled actions/github-script. Find an existing sticky comment with a marker like <!-- commit-ai -->; update it in place rather than spamming a fresh comment on every push.