---

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

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

Print without committing

To generate a commit message and print it without creating a Git commit:

aicommits --print # or --no-commit

This uses the first generated message and exits before running git commit.

Steer the first AI draft

Use --steer to give the model one-off context about what the commit is meant to accomplish before it writes the first draft:

aicommits --steer "Fix the page failing to load"

The steer text helps the model describe the intent of the change instead of only restating the diff. The diff remains the source of truth if the steer text conflicts with the code.

Guide output with Markdown

Commit message style is now controlled by a Markdown file instead of individual formatting flags.

By default, aicommits reads ~/.aicommits/message.md. The file is created automatically on first use.

aicommits

To use a different Markdown file for one run:

aicommits --message-file release-message.md

The default file includes editable instructions for language, title format, body rules, and style. If you were previously using settings like type, details, instructions, or conventional-*, upgrade once and those values will be migrated into message.md automatically.

Post-process the AI response

You can run an executable after the model responds and before the message is shown or committed.

aicommits --post-response-script rewrite-message.sh

The script receives the raw AI message on stdin and must write the final message to stdout.

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

Options

api-key

Required

API key for your configured API provider.

You can also keep the secret outside config.toml and reference an environment variable instead:

api-key = "env:OPENAI_API_KEY"

${OPENAI_API_KEY} is also supported if you prefer shell-style syntax.

base-url

Required

Base URL used for API 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"

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 model to use for generation.

api-mode

Default: responses

Controls which API primitive aicommits uses.

• responses: default and recommended for new setups
• chat: legacy compatibility mode

aicommits config set api-mode=chat

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

include-submodule-commits

Default: false

When a staged or uncommitted change updates a Git submodule pointer, include that submodule's commit log in the diff sent to the model. This gives the model the submodule commit subjects as context instead of only seeing the old and new submodule SHAs.

aicommits config set include-submodule-commits=true

message-path

Default: message.md

Relative paths resolve from ~/.aicommits/. The referenced Markdown file controls how commit messages should be written.

aicommits config set message-path=release-message.md

post-response-script

Default: empty

Relative paths resolve from ~/.aicommits/. The executable receives the AI response on stdin and must write the final commit message to stdout.

aicommits config set post-response-script=rewrite-message.sh

show-reasoning

Default: false

By default, aicommits shows normal analyzing progress.
If the API emits reasoning content, it switches to elapsed thinking time (for example The AI (gpt-5.4) is 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

reasoning-effort

Default: unset

Controls the model reasoning effort requested by aicommits.

• none, low, medium, high, xhigh: request an explicit reasoning level

This is the supported way to configure reasoning effort.
aicommits maps it to reasoning.effort for Responses API requests and reasoning_effort for Chat requests.

aicommits config set reasoning-effort=low

Or for a single run:

aicommits --reasoning-effort high

request-options

Default: empty

Raw JSON object merged into the selected API request body.

Use this for provider-specific fields that do not already have a dedicated aicommits option.
For reasoning effort, prefer reasoning-effort instead of passing reasoning or reasoning_effort manually.
Internal fields model, messages, instructions, input, 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 API provider using the Responses API by default, then returns the generated commit message. You can switch back to Chat Completions with api-mode=chat.

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.