aicommits: an AI commit message CLI for staged changes

The gap aicommits fills between git add and git commit

Most people stage a set of changes, then stare at the terminal trying to summarise them. aicommits sits exactly in that gap. The README describes it as "a CLI that writes your git commit messages for you with AI", and the usage flow is two commands: `git add <files...>` followed by `aicommits`. It reads the staged diff, sends it to an AI provider, prints the suggested message, and commits once you confirm.

The audience is narrow and clear. You need Node.js v22 or newer, an API key for one of the hosted providers, or a local model server. If your team already enforces a commit convention, the `--type` flag covers Conventional Commits, gitmoji and subject-plus-body shapes, so the generated text can match a lint rule rather than fight it. If you commit once a week, the setup cost is probably not worth it. If you commit a dozen times a day, the saved keystrokes compound.

How the generation flow works, and why providers differ

The CLI is written in TypeScript, builds to `dist/cli.mjs` with pkgroll, and exposes two binaries: `aicommits` and the shorter `aic`. It depends on the Vercel AI SDK packages (`ai`, `@ai-sdk/openai`, `@ai-sdk/openai-compatible`, `@ai-sdk/togetherai`) plus `cleye` for argument parsing and `@clack/prompts` for the interactive setup.

The README splits providers into two paths. Together AI, OpenAI, xAI and LM Studio use an "agentic generation flow", which means the model can call tools rather than answer in one shot. That matters because an agentic model can inspect the repository before writing the message instead of guessing from the diff alone. The fallbacks are explicit: Together models that were tested without compatible tool calls use the one-shot path, OpenAI, xAI and LM Studio fall back when an endpoint rejects tools, and LM Studio also falls back when a local model does not submit the required tool call. Other providers, including Groq, OpenRouter, Ollama and custom OpenAI-compatible endpoints, go through the one-shot flow.

So the quality of the generated message is not a property of aicommits alone. It depends on which provider you pick and whether that provider's model supports tool calls. A local LM Studio model that ignores tools will silently land on the simpler path. The repository includes `scripts/test-together-tool-compatibility.ts`, runnable via `pnpm test:together-tools`, which suggests tool compatibility is a known variable the maintainers track rather than assume.

Installing aicommits and generating your first message

The README states the minimum supported Node.js version is v22 and suggests checking it first.

node --version
npm install -g aicommits
aicommits setup

The setup command walks through provider selection, API key entry, model selection (fetched automatically when the provider supports it) and commit message format. It writes a `.aicommits` file in your home directory. For CI or headless environments the README shows the config file being written directly:

aicommits config set OPENAI_API_KEY="your_api_key_here"
aicommits config set OPENAI_BASE_URL="your_api_endpoint"
aicommits config set OPENAI_MODEL="your_model_choice"

The README warns that environment variables and the config file must be set consistently, because mixing an API key from one source with a base URL from another produces a mismatch. Once configured, the everyday flow is staging followed by generation:

git add .
aicommits

You should see a generated message and a confirmation prompt before anything is committed. If you would rather inspect the message first, `aicommits --clipboard` copies it instead of committing, and `aicommits --generate 3` produces three candidates to choose from, at the cost of more tokens.

The prepare-commit-msg hook and where it breaks

Running `aicommits hook install` inside a repository installs a `prepare-commit-msg` hook, so you can commit the way you normally do and edit the generated message before it is finalised. `aicommits hook uninstall` removes it. This is the integration most people actually want, because it keeps `git commit` as the entry point rather than adding a new command to muscle memory.

The failure mode is environmental. A hook that calls an AI provider needs a configured `.aicommits` file and network access at commit time. In a container that mounts the repository but not the home directory, or in a CI job that runs `git commit` on a machine with no credentials, the hook has nothing to work with. The README documents `aicommits config set` for exactly this reason, but it does not document what the hook does when generation fails, and it does not document rollback beyond `aicommits hook uninstall`. If you install the hook across many repositories, remember that it is per-repository: there is no global install step in the README, so a fresh clone needs the command again.

Custom prompts, token cost and the accuracy question

The `--prompt` flag is the escape hatch when the default output does not match your conventions. The README gives four examples: writing messages in Italian, focusing on performance implications, using technical jargon, and always naming the changed functions and file paths. That last one is the most useful for review, because a message that names the touched files is easier to search later.

The cost side is stated plainly. Generating multiple messages with `--generate <i>` "uses more tokens, meaning it costs more". There is no caching layer described, so every invocation sends the staged diff again. On a large refactor, that diff can be long, and the model sees all of it. aicommits is also fundamentally a summariser: it describes what changed, not whether the change is correct. A message that reads well can still describe a bug. Treat the output as a draft, which is exactly what the confirmation prompt and the `--clipboard` flag are for.

OpenCommit and the difference in approach

OpenCommit is the closest well-known alternative, and the difference is architectural rather than cosmetic. OpenCommit is distributed primarily as an npm package that hooks into git and supports a similar set of providers, but its configuration lives in git config keys rather than a `.aicommits` file, and it has historically leaned on a single generation path rather than the agentic-versus-one-shot split the aicommits README describes. If you already manage dotfiles and prefer everything under `~/.gitconfig`, that model is easier to audit. If you prefer a dedicated config file that a CI job can write with `aicommits config set`, aicommits is the cleaner fit.

The other distinction is the local-model story. aicommits lists Ollama and LM Studio as first-class providers, with LM Studio requiring no API key at all. That makes it viable on an air-gapped machine, though the README notes LM Studio falls back to the one-shot path when a local model does not submit the required tool call, so the agentic benefit may not apply to your local setup.

Licence, releases and what upgrading costs you

aicommits is MIT licensed, and the package.json confirms the `license` field and points the repository at `github.com/Nutlope/aicommits`. MIT is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and licence text are preserved. That is a description of the licence terms, not legal advice; if you redistribute a modified build, read the LICENSE file in the repository yourself.

Releases are automated. The `release` block in package.json runs semantic-release on the `develop` branch with conventionalcommits presets, so version numbers follow commit message conventions rather than manual tagging. The last push to the repository was on 2026-09-05, and v4.2.2 was released on 2026-09-04. Upgrading is a single command, `aicommits update`, which the README says detects npm, pnpm, yarn or bun and runs the matching install. The maintenance cost is mostly the provider surface: eight provider options and two generation paths mean a config that works today can behave differently after a release that changes fallback rules. Pinning a model explicitly with `aicommits config set OPENAI_MODEL` is the cheapest way to keep output stable across upgrades.

Editorial conclusion

Adopt aicommits if you already pay for an LLM API or run a local model server and you want commit messages generated from the staged diff without leaving the terminal. Skip it if you need deterministic output, if you cannot send source diffs to a third party, or if you expect the hook to work in a bare CI checkout. Before rolling it out, run aicommits --version, confirm the .aicommits file holds the provider and model you expect, and test one commit with --clipboard so nothing is committed until you have seen the message.

Frequently asked questions

Official sources

1. License: MIT
2. Nutlope/aicommits on GitHub
3. Project website
4. README
5. Releases