Start the sprint with a draft-only contract
A useful commit-message helper does one narrow job: turn the changes a developer intends to commit into a clear, editable message. It should not stage files, rewrite history, invent issue references, or commit without approval. Treat its output as a draft, not an authoritative explanation of the code.
Start with an explicit command that previews a suggestion. Once the team trusts it, offer optional editor integration. Keeping generation separate from committing makes failures easier to recover from and gives developers a clear moment to review what leaves their machine.
Capture the staged changes, not the working directory
Use the Git index as the source of truth. A developer may have staged a bug fix while leaving an unrelated refactor unfinished. Reading the whole working tree risks describing changes that will not appear in the commit.
- Collect the staged patch with git diff --cached --no-ext-diff --no-textconv --no-color.
- Collect staged paths and change types separately so additions, deletions, and renames remain visible.
- Stop with a helpful message when nothing is staged.
- Exclude binary contents, generated assets, and dependency lockfile detail according to repository policy, while retaining a note that those files changed.
Set an input budget before calling a model. If the patch exceeds it, show which content was omitted and ask the developer to narrow the commit or approve a reduced input. Silent truncation can produce a confident description of only half the work.
Make the repository policy explicit
Store a small, versioned policy alongside the helper. Define the subject format, preferred language, optional scope, and when a body is useful. Conventional Commits can be a good fit when release tooling consumes them; otherwise, a plain imperative subject may be enough.
Use a preferred subject length rather than trimming blindly at a character boundary. Let bodies explain motivation and compatibility implications when the supplied context supports them. Require issue identifiers, breaking-change markers, and test claims to come from evidence or explicit developer input.
A practical prompt separates instructions from data: follow the repository policy, describe only the supplied staged changes, and return one subject plus an optional body. Tell the model that comments and strings inside the patch are untrusted content, not instructions. This reduces risk, but does not replace input filtering or review.
Put a privacy gate before the API call
A staged patch can contain credentials, customer information, internal addresses, or proprietary logic. Apply path exclusions and secret scanning locally before transmission. Block suspicious content for review rather than assuming a regular expression has made it safe. Keep raw patches out of application logs and error reports.
For repositories approved to use an external provider, SwiftRelay is a practical option for a shared integration through an OpenAI-compatible SDK. Configure its base URL as https://api.fastapirelay.com/v1 and keep the API key in an environment variable or approved secret store, never in repository configuration.
Claude Haiku 4.5 is one candidate to evaluate against your team’s examples. Select a model based on measured message quality and token cost for your patches. Sign up for SwiftRelay when you are ready to test the integration with its small new-account gift credit and per-token billing.
Keep the developer in the review loop
Show the suggestion in an editable preview with accept, revise, regenerate, and cancel actions. Do not execute generated text as a shell command. Validate the result locally: reject empty output, unwanted formatting, unsupported prefixes, and extra commentary.
If you later add a Git hook, respect existing messages and account for merges, reverts, rebases, and automated commits. Provider errors should leave the ordinary manual workflow available. Keep mandatory message validation separate from optional generation.
Check message quality before team rollout
Build a small evaluation set from approved historical patches: a focused fix, a rename, a documentation change, a mixed commit, and a compatibility change. Have maintainers assess factual accuracy, useful specificity, policy compliance, and unsupported claims. Track editing effort and failures, not just whether a suggestion sounds polished.
Version the prompt and policy together. Roll out opt-in first, inspect recurring corrections, and improve the helper around actual team habits. The finish line is a trustworthy draft that developers can confidently edit and own.