back to home

Nutlope / aicommits

A CLI that writes your git commit messages for you with AI

8,856 stars
460 forks
13 issues
TypeScript
Chat with CodebaseArchitecture ScanSecurity AuditExplain Codebase

AI Architecture Analysis

This repository is indexed by RepoMind. By analyzing Nutlope/aicommits in our AI interface, you can instantly generate complete architecture diagrams, visualize control flows, and perform automated security audits across the entire codebase.

Our Agentic Context Augmented Generation (Agentic CAG) engine loads full source files into context, avoiding the fragmentation of traditional RAG systems. Ask questions about the architecture, dependencies, or specific features to see it in action.

Click here to launch the interactive analysis workspace

Embed this Badge

Showcase RepoMind's analysis directly in your repository's README.

[![Analyzed by RepoMind](https://img.shields.io/badge/Analyzed%20by-RepoMind-4F46E5?style=for-the-badge)](https://repomind-ai.vercel.app/repo/Nutlope/aicommits)
Preview:Analyzed by RepoMind

Repository Summary (README)

Preview
<div align="center"> <div> <img src=".github/screenshot.png" alt="AI Commits"/> <h1 align="center">AI Commits</h1> </div> <p>A CLI that writes your git commit messages for you with AI. Never write a commit message again.</p> <a href="https://www.npmjs.com/package/aicommits"><img src="https://img.shields.io/npm/v/aicommits" alt="Current version"></a> <a href="https://www.npmjs.com/package/aicommits"><img src="https://img.shields.io/npm/dt/aicommits" alt="Downloads"></a> </div>

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@develop

    We need @develop since v2 is still not released as latest/main!

  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)

  • Choosing your preferred commit message format (plain, conventional, or gitmoji)

    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
    • LM Studio (local) - No API key required. Runs on your computer via LM Studio
    • Custom OpenAI-compatible endpoint - Use any service that implements the OpenAI API

    For CI/CD environments, you can also set up configuration via the config file:

    aicommits config set OPENAI_API_KEY="your_api_key_here"
aicommits config set OPENAI_BASE_URL="your_api_endpoint"  # Optional, for custom endpoints
aicommits config set 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 install -g aicommits@develop

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: plain). Supports plain, 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.

Commit Message Formats

You can choose from three different commit message formats:

  • plain (default): Simple, unstructured commit messages
  • conventional: Conventional Commits format with type and scope
  • gitmoji: Emoji-based commit messages

Use the --type flag to specify the format:

aicommits --type conventional # or -t conventional
aicommits --type gitmoji       # or -t gitmoji
aicommits --type plain         # or -t plain (default)

This feature is useful if your project follows a specific commit message standard or if you're using tools that rely on these commit formats.

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: plain

The type of commit message to generate. Available options:

  • plain: Simple, unstructured commit messages
  • conventional: Conventional Commits format with type and scope
  • gitmoji: Emoji-based commit messages

Examples:

aicommits config set type=conventional
aicommits config set type=gitmoji
aicommits config set type=plain

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

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