AI Commits

A CLI that writes your git commit messages for you with AI. Never write a commit message again.

---

Setup

The minimum supported version of Node.js is v22. Check your Node.js version with node --version.

1. Install aicommits:

   npm install -g aicommits

2. Run the setup command to choose your AI provider:

   aicommits setup

This will guide you through:

• Selecting your AI provider (sets the provider config)

• Configuring your API key

• Automatically fetching and selecting from available models (when supported)

  Supported providers include:

  • TogetherAI (recommended) - Get your API key from TogetherAI
  • OpenAI - Get your API key from OpenAI API Keys page
  • OpenRouter - Get your API key from OpenRouter
  • Ollama (local) - Run AI models locally with Ollama
  • Custom OpenAI-compatible endpoint - Use any service that implements the OpenAI API

  Alternatively, you can use environment variables (recommended for CI/CD):

  export OPENAI_API_KEY="your_api_key_here"
  export OPENAI_BASE_URL="your_api_endpoint"  # Optional, for custom endpoints
  export OPENAI_MODEL="your_model_choice"     # Optional, defaults to provider default

  Note: When using environment variables, ensure all related variables (e.g., OPENAI_API_KEY and OPENAI_BASE_URL) are set consistently to avoid configuration mismatches with the config file.

  This will create a .aicommits file in your home directory.

Upgrading

Check the installed version with:

aicommits --version

If it's not the latest version, run:

npm update -g 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.

CLI Options

• --generate or -g: Number of messages to generate (default: 1)
• --exclude or -x: Files to exclude from AI analysis
• --all or -a: Automatically stage changes in tracked files for the commit (default: false)
• --type or -t: Git commit message format (default: conventional). Supports conventional and gitmoji
• --confirm or -y: Skip confirmation when committing after message generation (default: false)
• --clipboard or -c: Copy the selected message to the clipboard instead of committing (default: false)

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.

Generating Conventional Commits

If you'd like to generate Conventional Commits, you can use the --type flag followed by conventional. This will prompt aicommits to format the commit message according to the Conventional Commits specification:

aicommits --type conventional # or -t conventional

This feature can be useful if your project follows the Conventional Commits standard or if you're using tools that rely on this commit format.

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!

Environment Variables

You can also configure aicommits using environment variables instead of the config file.

Example:

export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://api.example.com"
export OPENAI_MODEL="gpt-4"
aicommits  # Uses environment variables

Configuration settings are resolved in the following order of precedence:

1. Command-line arguments
2. Environment variables
3. Configuration file
4. Default values

Configuration

Viewing current configuration

To view all current configuration options that differ from defaults, run:

aicommits config

This will display only non-default configuration values with API keys masked for security. If no custom configuration is set, it will show "(using all default values)".

Changing your model

To interactively select or change your AI model, run:

aicommits model

This will:

• Show your current provider and model
• Fetch available models from your provider's API
• Let you select from available models or enter a custom model name
• Update your configuration automatically

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 OPENAI_API_KEY

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

aicommits config get OPENAI_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 OPENAI_API_KEY=<your-api-key>

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

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

Config Options

OPENAI_API_KEY

Your OpenAI API key or custom provider API Key

OPENAI_BASE_URL

Custom OpenAI-compatible API endpoint URL.

OPENAI_MODEL

Model to use for OpenAI-compatible providers.

provider

The selected AI provider. Set automatically during aicommits setup. Valid values: openai, togetherai, ollama, custom.

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.

generate

Default: 1

The number of commit messages to generate to pick from.

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

timeout

The timeout for network requests to the OpenAI API in milliseconds.

Default: 10000 (10 seconds)

aicommits config set timeout=20000 # 20s

max-length

The maximum character length of the generated commit message.

Default: 72

aicommits config set max-length=100

type

Default: "" (Empty string)

The type of commit message to generate. Set this to "conventional" to generate commit messages that follow the Conventional Commits specification:

aicommits config set type=conventional

You can clear this option by setting it to an empty string:

aicommits config set type=

How it works

This CLI tool runs git diff to grab all your latest code changes, sends them to the configured AI provider (TogetherAI by default), then returns the AI 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

• Hassan El Mghari: @Nutlope

• Riccardo Giorato: @riccardogiorato

• Hiroki Osame: @privatenumber

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