commitpreflight is a preflight lint tool for commit messages written by AI coding agents. Its role is to check whether a commit message is compliant before the agent calls git commit, thereby avoiding wasting a round of conversation on rewriting because of a hook rejection.
Purpose When an AI coding agent generates a commit message and executes git commit, it may be rejected by a hook, causing the agent to need an extra round to fix it. commitpreflight catches such problems before the commit occurs and gives specific fix suggestions rather than merely reporting errors.
Rule Sources The tool's rule set is not based on style preferences, but is driven by real failure data: a cluster of autonomous coding agents recorded 10,976 CLI failures within 7 days, of which about one fifth were malformed commit messages, the largest category of agent CLI failures in that corpus.
A key detail is the shape of overruns: 81% of overruns are off by only 10 characters or fewer. Agents do not write long essays in the subject line, but merely slightly exceed the limit. Therefore the appropriate intervention is to trim at the last word boundary, which is what commitpreflight suggests; when the overrun is too large and trimming would amount to rewriting, it does not give a trimming suggestion.
Usage
- As a GitHub Action: lint every commit message in a pull request in CI.
- Use with pre-commit.
- Use as a git hook.
- Call from an agent: --json outputs a machine-readable list, so the agent can act on it without parsing natural language.
- Call directly.
- Optional configuration: set it in pyproject.toml.
Exit Codes and Strict Mode When any finding at the error level appears, the exit code is 1; otherwise it is 0. Use --strict to make warnings blocking errors as well.
Applicable Scenarios Suitable for development workflows that use AI coding agents to automatically generate commit messages, especially scenarios where commit messages need preflight checking in CI, pre-commit, or git hook stages, and also suitable for automated workflows where agents need to obtain fix suggestions in a machine-readable way.
Limitations and Pricing The material does not provide more information about platform compatibility, specific rule lists, installation command details, performance, or guarantees of effectiveness. The material mentions that if it is needed across AI agents at scaleto run commitpreflight for the group, a team subscription is available at $100 per month.
