https://github.com/negoziator/ai-commit
Autonomous git commits
https://github.com/negoziator/ai-commit
ai automated-commits autonomous commit-message developer-tool npm-cli
Last synced: about 1 month ago
JSON representation
Autonomous git commits
- Host: GitHub
- URL: https://github.com/negoziator/ai-commit
- Owner: negoziator
- License: mit
- Created: 2023-10-07T17:55:55.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2025-11-20T13:02:43.000Z (about 1 month ago)
- Last Synced: 2025-11-20T15:05:34.663Z (about 1 month ago)
- Topics: ai, automated-commits, autonomous, commit-message, developer-tool, npm-cli
- Language: TypeScript
- Homepage:
- Size: 3.35 MB
- Stars: 19
- Watchers: 1
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
🤖 AI-Commit 🤖
A powerful CLI tool that uses AI to generate meaningful, insightful git commit messages based on your code changes.
---
## Table of Contents
- [Features](#features)
- [Setup](#setup)
- [Installation](#installation)
- [Upgrading](#upgrading)
- [Usage](#usage)
- [CLI Mode](#cli-mode)
- [Git Hook Integration](#git-hook-integration)
- [LLM Providers](#llm-providers)
- [OpenAI (Default)](#openai-default)
- [Anthropic Claude](#anthropic-claude)
- [Azure OpenAI](#azure-openai)
- [Ollama (Local)](#ollama-local)
- [Custom/RAG](#customrag)
- [Configuration](#configuration)
- [Options](#options)
- [Environment Variables (.env)](#environment-variables-env)
- [Project-Specific Configuration](#project-specific-configuration)
- [Maintainers](#maintainers)
- [Contributing](#contributing)
## Features
- 🤖 **AI-Powered Commits**: Generates meaningful commit messages based on your code changes
- 🔄 **Git Integration**: Works seamlessly with your existing Git workflow
- 🪝 **Git Hook Support**: Can be installed as a Git hook for automatic message generation
- 🌐 **Multiple Languages**: Supports commit messages in different locales
- ⚙️ **Customizable**: Configure the AI model, message length, and other parameters
- 📝 **Project Context**: Add project-specific context to improve message relevance
- 🔌 **Multiple LLM Providers**: Choose from OpenAI, Anthropic, Azure OpenAI, Ollama, or custom endpoints
## Setup
> A minimum of Node v20 is required. Check your Node.js version with `node --version`.
### Installation
1. **Install AI-Commit:**
```sh
npm install -g @negoziator/ai-commit
```
2. **Choose and configure your LLM provider:**
**Option A: OpenAI (Default)**
```sh
aicommit config set OPENAI_KEY=
```
Get your API key from [OpenAI Platform](https://platform.openai.com/account/api-keys)
**Option B: Anthropic Claude**
```sh
aicommit config set provider=anthropic
aicommit config set ANTHROPIC_KEY=
```
Get your API key from [Anthropic Console](https://console.anthropic.com/)
**Option C: Ollama (Local, Free)**
```sh
# Install Ollama from https://ollama.com, then:
ollama pull llama3.2
aicommit config set provider=ollama
aicommit config set model=llama3.2
```
**Option D: Azure OpenAI**
```sh
aicommit config set provider=azure-openai
aicommit config set AZURE_OPENAI_KEY=
aicommit config set AZURE_ENDPOINT=
```
See the [LLM Providers](#llm-providers) section for more options and details.
### Upgrading
```sh
npm update -g @negoziator/ai-commit
```
## Usage
### CLI Mode
Use `aicommit` directly to generate a commit message for your staged changes:
```sh
git add
aicommit
```
Example workflow:
```
$ git add .
$ aicommit
✓ Analyzing your changes...
✓ Generating commit message...
AI-generated commit message:
feat: add project-specific configuration support via .ai-commit.json
? Use this message? › (Y/n)
```
### Git Hook Integration
You can set up AI-Commit as a Git hook to automatically generate commit messages:
```sh
# Install the prepare-commit-msg hook
aicommit hook install
```
This will add a Git hook that automatically suggests commit messages when you run `git commit`.
To uninstall the hook:
```sh
aicommit hook uninstall
```
## LLM Providers
AI-Commit supports multiple LLM providers, allowing you to choose the best option for your needs.
### OpenAI (Default)
The default provider using OpenAI's GPT models.
**Setup:**
```sh
aicommit config set OPENAI_KEY=
```
**Recommended models:**
- `gpt-4o-mini` (default, fast and cost-effective)
- `gpt-4o` (more capable, higher cost)
- `gpt-4-turbo`
**Get your API key:** [OpenAI Platform](https://platform.openai.com/account/api-keys)
---
### Anthropic Claude
Use Anthropic's Claude models as an alternative to OpenAI.
**Setup:**
```sh
aicommit config set provider=anthropic
aicommit config set ANTHROPIC_KEY=
```
**Recommended models:**
- `claude-3-5-sonnet-20241022` (recommended, best balance)
- `claude-3-opus-20240229` (most capable)
- `claude-3-haiku-20240307` (fastest, most economical)
**Get your API key:** [Anthropic Console](https://console.anthropic.com/)
---
### Azure OpenAI
Use Azure's OpenAI Service for enterprise deployments.
**Setup:**
```sh
aicommit config set provider=azure-openai
aicommit config set AZURE_OPENAI_KEY=
aicommit config set AZURE_ENDPOINT=
```
**Example endpoint:** `https://your-resource.openai.azure.com`
**Note:** The `model` config should match your Azure deployment name.
**Learn more:** [Azure OpenAI Service](https://azure.microsoft.com/en-us/products/ai-services/openai-service)
---
### Ollama (Local)
Run AI-Commit completely offline using local models via Ollama.
**Setup:**
```sh
# 1. Install Ollama from https://ollama.com
# 2. Pull a model
ollama pull llama3.2
# 3. Configure AI-Commit
aicommit config set provider=ollama
aicommit config set model=llama3.2
```
**Recommended models:**
- `llama3.2` (recommended, good balance)
- `codellama` (optimized for code)
- `mistral` (fast and capable)
- `qwen2.5-coder` (specialized for coding)
**Default endpoint:** `http://localhost:11434` (automatically configured)
**Benefits:**
- ✅ Completely free
- ✅ Works offline
- ✅ Privacy-focused (data never leaves your machine)
- ✅ No API key required
---
### Custom/RAG
Connect to custom LLM endpoints, RAG systems, or OpenAI-compatible APIs.
**Setup:**
```sh
aicommit config set provider=custom
aicommit config set CUSTOM_ENDPOINT=
aicommit config set CUSTOM_KEY=
```
**Compatible with:**
- Custom RAG implementations
- LM Studio
- LocalAI
- Text Generation WebUI
- vLLM
- Any OpenAI-compatible API
**Example:**
```sh
aicommit config set provider=custom
aicommit config set CUSTOM_ENDPOINT=https://my-rag.example.com/v1/chat/completions
aicommit config set model=my-custom-model
```
---
## Configuration
Manage configuration using the `aicommit config` command.
To get a configuration option value, use the command:
```sh
aicommit config get
```
For example, to retrieve the API key, you can use:
```sh
aicommit config get OPENAI_KEY
> sk_1234567890
```
To set a configuration option, use the command:
```sh
aicommit config set =
```
### Options
#### General Options
| Option | Default | Description |
|---------------------|-----------------|---------------------------------------------------------------------------------------|
| `provider` | `openai` | LLM provider to use (`openai`, `anthropic`, `azure-openai`, `ollama`, `custom`) |
| `locale` | `en` | Locale for the generated commit messages |
| `generate` | `1` | Number of commit messages to generate |
| `model` | `gpt-4o-mini` | The model to use (provider-specific) |
| `timeout` | `10000` | Network request timeout in milliseconds |
| `max-length` | `50` | Maximum character length of the generated commit message |
| `type` | `""` | Type of commit message to generate (`conventional` or empty) |
| `auto-confirm` | `false` | Automatically confirm the generated commit message without user prompt |
| `prepend-reference` | `false` | Prepend issue reference from branch name to commit message |
| `temperature` | `0.2` | Temperature (0.0-2.0) to control randomness of the output |
| `max-completion-tokens` | `10000` | Maximum number of tokens that can be generated in the completion |
| `proxy` | N/A | HTTPS proxy URL (e.g., `http://proxy.example.com:8080`) |
#### Provider-Specific Options
| Option | Provider | Description |
|---------------------|-----------------|---------------------------------------------------------------------------------------|
| `OPENAI_KEY` | OpenAI | OpenAI API key (starts with `sk-`) |
| `ANTHROPIC_KEY` | Anthropic | Anthropic API key (starts with `sk-ant-`) |
| `AZURE_OPENAI_KEY` | Azure OpenAI | Azure OpenAI API key |
| `AZURE_ENDPOINT` | Azure OpenAI | Azure OpenAI endpoint URL (e.g., `https://your-resource.openai.azure.com`) |
| `OLLAMA_ENDPOINT` | Ollama | Ollama server endpoint (default: `http://localhost:11434`) |
| `CUSTOM_ENDPOINT` | Custom | Custom API endpoint URL |
| `CUSTOM_KEY` | Custom | Custom API key (optional, for endpoints requiring authentication) |
### Environment Variables (.env)
For local development, you can create environment files in your project root:
**For CLI usage** (`.env`):
```bash
# .env - Used when running aicommit
provider=anthropic
ANTHROPIC_KEY=sk-ant-...
model=claude-3-5-sonnet-20241022
max-length=80
```
**For testing** (`.env.local`):
```bash
# .env.local - Used when running npm test
OPENAI_KEY=sk-...
# or
provider=anthropic
ANTHROPIC_KEY=sk-ant-...
```
**File usage:**
- `.env` → Loaded when running `aicommit` (CLI usage)
- `.env.local` → Loaded when running `npm test` (local testing only)
- Both files are gitignored for security
**Priority order** (highest to lowest):
1. `.ai-commit.json` (project-specific)
2. CLI arguments
3. Environment variables (`.env`, `.env.local`, or shell)
4. Global config (`~/.aicommit`)
**Note:** See `.env.example` for all available options. Copy it to `.env` for CLI usage or `.env.local` for testing.
### Project-Specific Configuration
You can add a `.ai-commit.json` file in the root of your project to provide additional context about your project to the AI and to override global configuration settings for the specific project.
**Example with OpenAI:**
```json
{
"projectPrompt": "This is a Node.js CLI tool that uses AI to generate meaningful git commit messages.",
"model": "gpt-4o",
"locale": "en",
"max-length": "100",
"temperature": "0.5"
}
```
**Example with Anthropic:**
```json
{
"provider": "anthropic",
"ANTHROPIC_KEY": "sk-ant-...",
"model": "claude-3-5-sonnet-20241022",
"projectPrompt": "This is a TypeScript library for data validation.",
"max-length": "80"
}
```
**Example with Ollama:**
```json
{
"provider": "ollama",
"model": "codellama",
"projectPrompt": "This is a Python web application using FastAPI.",
"temperature": "0.3"
}
```
The `.ai-commit.json` file can contain any of the configuration options listed in the [Options](#options) section. Values set in this file will take precedence over the global configuration.
The `projectPrompt` field should contain a brief description of your project, its purpose, and any other relevant information that would help the AI understand the context of your code changes.
## Maintainers
[](https://twitter.com/negoziator)
## Contributing
If you want to help fix a bug or implement a feature in [Issues](https://github.com/negoziator/ai-commit/issues), checkout
the [Contribution Guide](CONTRIBUTING.md) to learn how to setup and test the project.