Setup

The minimum supported version of Node.js is the latest v14. Check your Node.js version with node --version.

1. Install aicommits:

   npm install -g @sugarmo/aicommits

2. Retrieve your API key from your API provider

   Note: If you haven't already, you'll have to create an account and set up billing.

3. Set the key so aicommits can use it:

   aicommits config set api-key=<your token>

   This will create ~/.aicommits/config.toml.

Upgrading

Check the installed version with:

aicommits --version

If it's not the latest version, run:

npm update -g @sugarmo/aicommits

Usage

CLI mode

You can call aicommits directly to generate a commit message for your staged changes:

git add <files...>
aicommits

aicommits passes down unknown flags to git commit, so you can pass in commit flags.

For example, you can stage all changes in tracked files with as you commit:

aicommits --all # or -a

👉 Tip: Use the aic alias if aicommits is too long for you.

Generate multiple recommendations

Sometimes the recommended commit message isn't the best so you want it to generate a few to pick from. You can generate multiple commit messages at once by passing in the --generate <i> flag, where 'i' is the number of generated messages:

aicommits --generate <i> # or -g <i>

Warning: this uses more tokens, meaning it costs more.

Non-interactive environments (Git GUI, external clients, CI)

If your environment does not provide an interactive TTY, skip prompts explicitly:

aicommits --confirm # or -y / --yes

Generate title + optional details

Enable details when you want a body only when the title is not clear enough on its own:

aicommits --details

If you prefer a bullet-list body style:

aicommits --details --details-style list

Default style

The generator uses a GitHub Copilot-like style by default and prefers commit titles with a concrete file/class/module anchor so commit lists are easier to scan.

You can still fine-tune output using custom instructions:

aicommits --details --instructions "Use shorter body sentences and prioritize class names in the title"

Customize conventional format

You can combine conventional commits with custom output format and type mapping:

aicommits --type conventional --conventional-format "<type>(<scope>): <subject>" --conventional-types '{"feature":"Introduce a feature","bugfix":"Fix defects"}'

By default, conventional mode omits scope and uses type: subject. You can enable scope preference (for example refactor(RecentScrollshotController): ...) when there is a clear dominant file/class/module:

aicommits --conventional-scope true

Git hook

You can also integrate aicommits with Git via the prepare-commit-msg hook. This lets you use Git like you normally would, and edit the commit message before committing.

Install

In the Git repository you want to install the hook in:

aicommits hook install

Uninstall

In the Git repository you want to uninstall the hook from:

aicommits hook uninstall

Usage

1. Stage your files and commit:

   git add <files...>
   git commit # Only generates a message when it's not passed in

   If you ever want to write your own message instead of generating one, you can simply pass one in: git commit -m "My message"

2. Aicommits will generate the commit message for you and pass it back to Git. Git will open it with the configured editor for you to review/edit it.

3. Save and close the editor to commit!

Configuration

Runtime configuration is read from ~/.aicommits/config.toml (and CLI flags). Environment variables are not used as config inputs.

The file format is TOML.

Reading a configuration value

To retrieve a configuration option, use the command:

aicommits config get <key>

For example, to retrieve the API key, you can use:

aicommits config get api-key

You can also retrieve multiple configuration options at once by separating them with spaces:

aicommits config get api-key generate

Setting a configuration value

To set a configuration option, use the command:

aicommits config set <key>=<value>

For example, to set the API key, you can use:

aicommits config set api-key=<your-api-key>

You can also set multiple configuration options at once by separating them with spaces, like

aicommits config set api-key=<your-api-key> generate=3 locale=en

Options

api-key

Required

API key for your chat completions provider.

base-url

Required

Base URL used for chat completions requests.

aicommits config set base-url=https://api.openai.com/v1

profile

Default: empty

Selects a named profile from the profiles table in config.toml. When a profile is selected, profile values override top-level values.

aicommits config set profile=openai

Example:

api-key = "top-level-key"
model = "gpt-4o-mini"
profile = "openai"

[profiles.openai]
model = "gpt-5.2-codex"
base-url = "https://api.example.com/v1"

locale

Default: en

The locale to use for the generated commit messages. Consult the list of codes in: https://wikipedia.org/wiki/List_of_ISO_639-1_codes.

Common aliases are normalized automatically (for example cn -> zh-CN).

generate

Default: 1

The number of commit messages to generate to pick from.

Note, this will use more tokens as it generates more results.

proxy

Set a HTTP/HTTPS proxy to use for requests.

To clear the proxy option, you can use the command (note the empty value after the equals sign):

aicommits config set proxy=

model

Default: gpt-3.5-turbo

The Chat Completions (/v1/chat/completions) model to use.

timeout

The timeout for network requests to the API in milliseconds.

Default: 10000 (10 seconds)

aicommits config set timeout=20000 # 20s

context-window

Default: 0 (auto/default compaction budget)

Set model context size (tokens) so diff compaction can scale to your provider/model window and reduce truncation on large commits.

When set, aicommits reserves part of the window for system prompt and output, then compacts the diff to fit the remaining budget.

aicommits config set context-window=32768

You can also use K / M suffixes:

aicommits config set context-window=32K
aicommits config set context-window=1M

Use 0 to switch back to auto mode:

aicommits config set context-window=0

max-length

The maximum character length of the generated commit message.

Default: 50

aicommits config set max-length=100

type

Default: plain format

Set commit type formatting:

aicommits config set type=conventional

details

Default: false

Set this to true to allow optional body details. If the title already explains the change clearly, it can still return title only:

aicommits config set details=true

details-style

Default: paragraph

Controls body formatting when details=true.

Allowed values: paragraph, list

aicommits config set details-style=list

show-reasoning

Default: false

By default, aicommits shows normal analyzing progress.
If the model emits reasoning tokens, it switches to elapsed thinking time (for example Thinking for 1m 12s). Enable this option to print full streamed model reasoning (debug mode):

aicommits config set show-reasoning=true

Or enable for a single run:

aicommits --show-reasoning

instructions

Default: empty

Additional custom prompt instructions:

aicommits config set instructions="Use short and direct wording"

conventional-format

Default: <type>[optional (<scope>)]: <commit message>

Customize the conventional output template:

aicommits config set conventional-format="<type>(<scope>): <subject>"

conventional-types

Default: built-in conventional type map

Customize type descriptions with JSON:

aicommits config set conventional-types='{"feature":"Introduce a feature","bugfix":"Fix defects"}'

conventional-scope

Default: false

When enabled, conventional commits strongly prefer type(scope): subject using the primary file/class/module as scope.
When disabled (default), conventional commits prefer type: subject.

aicommits config set conventional-scope=true

request-options

Default: empty

Raw JSON object merged into the Chat Completions request body.

Use this for provider-specific fields (for example, disabling reasoning/thinking when supported).
Internal fields model, messages, and stream are controlled by aicommits and cannot be overridden.

aicommits config set request-options='{"thinking":{"type":"disabled"}}'

How it works

This CLI tool runs git diff to grab your latest code changes, sends them to your configured chat completions API, then returns the generated commit message.

Video coming soon where I rebuild it from scratch to show you how to easily build your own CLI tools powered by AI.

Maintainers

• Steven Mok: @sugarmo

Contributing

If you want to help fix a bug or implement a feature in Issues, checkout the Contribution Guide to learn how to setup and test the project.