guanguans/ai-commit: AI commit messages from your terminal, not your editor

What guanguans/ai-commit solves, and for whom

Writing a commit message is a small tax that most developers pay badly. The diff is already in the index; the message is a summary of that diff, and the summary is what reviewers read first. guanguans/ai-commit takes the staged changes, sends them to a language model, and returns a message shaped like `type(scope): subject` plus a bulleted body. The README describes it as a tool that will "Automagically generate conventional git commit message with AI."

The audience is narrow but real: people who commit from a terminal and who already care about Conventional Commits. If your team enforces commitlint or generates a changelog from commit types, the value is that the type prefix comes from the model rather than from your memory at 6pm. If your team writes free-form messages and never parses them, the tool adds a dependency and an API call for very little.

It is not an editor integration. The related searches around "AI commit VSCode" and "ai commit message generator intellij" point at a different category of product. This one is a CLI you invoke, either as a downloaded binary or as a Composer package. That distinction matters more than any feature list: the tool has no GUI, no diff viewer, and no inline suggestion popup.

How the generator pipeline works

The architecture is a small pipeline with swappable ends. On one side is a generator: a named backend such as `openai_chat`, `openai`, `moonshot`, `ernie_bot`, `ernie_bot_turbo`, `bito_cli`, `github_copilot_cli`, or `github_models_cli`. On the other side is git itself. The README's sample output shows the sequence plainly: the tool prints `Generating commit message`, then runs the backend (in the example, the `bito` binary), then prints a JSON object with `subject` and `body` fields, then renders a confirmation table before committing.

Two families of generators sit behind that interface. API-key generators (OpenAI, OpenAI Chat, Moonshot, ERNIE) send the diff to a remote endpoint using a key you configure. CLI generators (Bito CLI, GitHub Copilot CLI, GitHub Models CLI) shell out to a local binary, which is why the config keys for those are named `generators.bito_cli.binary` and `generators.github_copilot_cli.binary` rather than `api_key`. The README marks both binary paths as optional, implying a default binary name on PATH.

There is also an interactive step in the flow. The sample session shows a commit-type prompt with options from `auto` through `revert`, and the chosen type (`chore` in the example) is passed to the model. The model then returns a structured `subject` and `body`. So the tool is not purely autonomous: it can ask you for the type, or infer it when you pick `auto`. That design keeps the model's output inside the Conventional Commits vocabulary instead of hoping it guesses the right prefix.

Installing guanguans/ai-commit and generating a first message

The README gives two installation routes. The first downloads a prebuilt `ai-commit` file from the `builds/` directory in the repository and marks it executable. The second installs through Composer, either globally or into a project as a dev dependency. The PHP requirement is stated as PHP >= 8.2, so a machine on 8.1 will fail before it reaches any AI call.

The download route needs no PHP toolchain on your side, which is the practical choice for a machine where you do not want a global Composer bin directory:

curl 'https://raw.githubusercontent.com/guanguans/ai-commit/main/builds/ai-commit' -o ai-commit -#
chmod +x ai-commit

If you prefer Composer, the README shows a global install. The `--dev` flag is part of the documented command, so keep it if you copy the line verbatim:

composer global require guanguans/ai-commit --dev -v

Configuration is done with `config set`, and each generator has its own key. For an OpenAI Chat backend the README uses `generators.openai_chat.api_key` with a value starting `sk-`. The `--global` flag writes the setting outside the current repository, which is what you want for a personal key:

./ai-commit config set generators.openai_chat.api_key sk-... --global
./ai-commit config set generator openai_chat --global

The second line sets the default generator, which the README marks as optional. After that, stage something and run the commit command. The `--generator` flag overrides the default for a single invocation, and the README's example also passes `--no-edit` and `--no-verify`:

./ai-commit commit
./ai-commit commit --generator=github_copilot_cli

What you should see is the three-step output from the README: a generation step, a confirmation table showing `subject` and `body`, and a prompt asking `Do you want to commit this message? (yes/no) [yes]`. Answering yes produces the `Successfully generated and committed message.` line. If the backend is misconfigured you will see the generator's stderr interleaved in the output, as the sample session does with the `ERR Model in use: BASIC` lines from Bito.

Where the CLI model breaks down

The confirmation prompt is the main safety net, and it is also the main cost. Every commit becomes an interactive exchange unless you pass flags that skip it. The README demonstrates `--no-edit` and `--no-verify` in the same command, which is a combination worth thinking about before you copy it into an alias. `--no-verify` skips git hooks, so a pre-commit hook that runs tests or a commit-msg hook that runs commitlint will not fire. If your team relies on commitlint to reject malformed messages, disabling the hook removes the check that the tool is nominally designed to satisfy.

The second limitation is the diff itself. The tool reads staged changes and sends them to a model. The README does not document any redaction, allowlist, or file-pattern exclusion for what gets sent. On a repository where staged files can contain credentials, internal hostnames, or customer data, that is a decision you make per commit, not a setting the tool makes for you. The README is silent on this point, and silence here should be read as "no documented control."

The third is the backend dependency. API generators require a working key and network access; CLI generators require the corresponding binary to be installed and authenticated (Bito CLI, GitHub Copilot CLI, GitHub Models CLI). The README marks the binary paths as optional, which suggests a default name on PATH, but it does not document what happens when the binary is missing. A failure at commit time is a worse place to discover a broken setup than a dry run earlier in the day.

Compared with commitizen and editor-side generators

The nearest well-known tool is commitizen, which the repository lists as a topic. The difference is where the intelligence sits. commitizen is a prompt-driven wizard: it asks you for the type, the scope, the subject, and the body, and you type each one. It enforces the Conventional Commits shape through questions, not through a model, and it never reads your diff. guanguans/ai-commit inverts that: the model reads the diff and proposes the fields, and you confirm or reject. If your problem is "I know what to write but I forget the type list," commitizen solves it without an API key. If your problem is "I do not want to write the body at all," this tool is the one that addresses it.

The other comparison is against editor extensions, which the related searches keep surfacing. A VS Code or IntelliJ extension puts the generated message next to the diff, in the same window where you are reviewing changes. guanguans/ai-commit puts it in the terminal, after you have already staged. That is a real workflow difference, not a cosmetic one: terminal-first users will find the CLI faster, and editor-centric users will find it a context switch. There is no VS Code extension here, and the repository does not claim one.

Maintenance, licence, and the cost of upgrading

The repository is not archived, and its last push was on 2026-09-12. The most recent tagged release listed is 1.15.5 from 2025-05-17, with 1.15.4 on 2025-05-03 and 1.15.3 on 2024-11-10 before that. The gap between the last release and the last push means the main branch has moved since the last tag, so if you install from the `builds/ai-commit` file on `main` you are tracking unreleased code rather than a tagged artifact. That is the upgrade cost in one sentence: pin to a release if you want stability, or track `main` and accept that the downloaded binary changes under you.

The licence is MIT, which is permissive and imposes no copyleft obligation on your own code. That is a statement about the licence text, not legal advice; if you redistribute the binary inside a commercial product, read the LICENSE file in the repository rather than this paragraph. The PHP >= 8.2 floor is the other ongoing cost. It is a recent runtime, and teams still on 8.0 or 8.1 cannot use the Composer route at all. The standalone download avoids that constraint because it ships as a built file, but the README does not state which PHP version that build embeds.

Editorial conclusion

Adopt guanguans/ai-commit if you already commit from a shell, want conventional-commit types enforced by a prompt, and are willing to keep an API key or a local model CLI around. Skip it if your commit flow lives inside an editor extension, or if you cannot run PHP 8.2 or download the standalone build. Before wiring it into a team, verify three things on your own machine: that `ai-commit config set generators.openai_chat.api_key` writes where you expect, that `ai-commit commit --generator=openai_chat --no-verify` produces a message you would actually keep, and that the generated body does not leak secrets from the staged diff. The repository's last push was on 2026-09-12, so the code is current, but the README does not document a rollback path if a generated message is committed unedited.

Frequently asked questions

Official sources

1. guanguans/ai-commit on GitHub
2. Issues
3. License: MIT
4. README
5. Releases