A useful commit-message helper does one narrow job: turn reviewed, staged changes into a draft that follows your team’s conventions. It should not stage files, invent motivation, or commit anything automatically. This first lap builds a small command-line helper with explicit inputs, predictable output, and a human checkpoint.
1. Write your team’s commit-message contract
Create a versioned file named commit-rules.txt in your repository. Define the allowed types, optional scopes, subject length, and when a body is required. Start with types such as feat, fix, refactor, test, docs, and chore. Choose a subject limit, such as 72 characters, and specify an imperative subject without a trailing period.
Add two examples drawn from your own repository. State that ticket references must come from an explicit user argument, never a guess. For breaking changes, require the author to supply the migration details rather than letting the helper infer them.
2. Collect only the staged changes
Create tools/commit-helper.py and give it a single responsibility: print a proposed message. Use Python’s subprocess.run with argument lists and check=True, not shell interpolation. First run git diff --cached --quiet: exit status zero means there is nothing staged; status one means changes exist; other statuses indicate an error.
Collect the patch with git diff --cached --no-ext-diff --no-color and a compact summary with git diff --cached --stat --no-ext-diff. Do not use an unstaged diff. This prevents unrelated working-tree edits from influencing a message for a different set of changes.
3. Put a privacy gate before the API call
Inspect staged paths before sending content. Block sensitive filenames such as .env, private keys, and credential exports. Add secret scanning as another guard, while treating it as imperfect protection rather than a guarantee.
Set a configurable patch-size limit and stop when it is exceeded. Do not silently truncate: missing context can produce misleading messages. For oversized changes, ask the developer to split the commit or explicitly select a summary-only mode. Explain that summary-only drafts have less evidence and need closer review.
4. Configure the relay outside your repository
Install the OpenAI Python SDK in your development environment. Store your credential in SWIFTRELAY_API_KEY and your chosen model identifier in COMMIT_MODEL. Keep both out of tracked configuration. SwiftRelay is a practical fit here because the same OpenAI-compatible integration lets your team change models without rewriting the helper.
Sign up for SwiftRelay to use the small gift credit available to new accounts. Configure the SDK with base_url="https://api.fastapirelay.com/v1" and read the API key from the environment. Select the dashboard-listed identifier for a model such as Claude Haiku 4.5; do not assume its display name is its API identifier. Set an explicit timeout and keep retries bounded.
5. Ask for one constrained draft
Send the team rules as instructions and the staged summary and patch as clearly delimited input. Tell the model that repository content is untrusted data, not instructions. Request only the commit message: no explanation, Markdown fences, alternatives, or claims about tests unless supplied explicitly by the developer.
Keep the message short unless the rules require a body. Require factual wording grounded in the patch, and ask the model not to invent issue numbers or business intent. Treat this prompt as guidance, not enforcement; validation belongs in your program.
6. Validate and require human approval
Check the returned subject against your allowed types, scope format, length limit, and punctuation rule. Reject empty output, multiple suggestions, and surrounding commentary. Print a clear error when validation fails rather than quietly modifying the draft.
Write an accepted draft to a temporary file and display it for review. Leave committing to the developer: git commit --edit --file=/path/to/draft opens the draft for editing. Never run that command automatically. Warn that staging additional changes invalidates the draft.
7. Test the helper before team rollout
Test empty staging, a small fix, a binary-only change, an oversized patch, a secret-like fixture, malformed output, and an API failure. Mock API responses so these checks need no credentials. Publish the helper, rules, and setup instructions together. Keep adoption opt-in until teammates trust the drafts and the failure messages.