ai-commit 🤖

An AI-powered conventional commit message generator. Stage your changes, run ai-commit generate, and get an instant commit message that follows the Conventional Commits spec. Confirm, edit, or cancel — you're always in control.

Features

• ⚡ Instant commit messages — analyzes your staged diff and generates a meaningful message
• 📋 Conventional Commits — always follows type: description format
• 🔄 Swappable AI providers — Gemini (free), OpenAI, or Claude
• 🎛️ Configurable — customize commit types, scope rules, and message length
• ✏️ Always editable — confirm, edit, or cancel before anything is committed
• 🏠 Per-project overrides — ai-commit init --local generates .commitrc.json for team-specific conventions
• 🎫 Ticket number support — auto-extracts Jira, GitHub, or custom ticket numbers from your branch name

Quick Start

npm install -g @julianabot/ai-commit
ai-commit init
ai-commit generate

Getting Started

1. Install

npm install -g @julianabot/ai-commit

2. Get a free Gemini API key

1. Go to https://aistudio.google.com/app/apikey
2. Sign in with a Google account
3. Click Create API Key
4. Copy the key (starts with AIza...)

Free tier: 15 requests/min, 1 million tokens/day

3. Run global setup

ai-commit init

This walks you through:

✔ Which AI provider? › Gemini Flash (free tier available) — recommended
✔ Enter your gemini API key › AIza...
✔ Commit types (comma separated) › feat, fix, docs, style, refactor, test, chore
✔ Require a scope in commit messages? › No
✔ Maximum commit message length › 72
✅ Config saved to ~/.ai-commit/config.json

4. (Optional) Set up per-project config

cd your-project
ai-commit init --local

This generates a .commitrc.json in the current directory. Commit it to share conventions with your team.

✔ Commit types (comma separated) › feat, fix, docs, style, refactor, test, chore
✔ Require a scope? › No
✔ Max message length › 72
✔ Does this project use ticket numbers? › Yes
✔ What ticket format? › Jira style (e.g. PROJ-12345)
✔ Enter your ticket prefix › PROJ
✅ Local config saved to .commitrc.json

5. Generate your first commit

git add .
ai-commit generate

✔ Commit message generated!

Generated commit message:
feat: add OAuth2 login with Google provider

✔ What would you like to do? › ✅ Confirm — commit as is
[main a03e3f3] feat: add OAuth2 login with Google provider
✅ Committed successfully!

Ticket Number Support

If your project uses ticket numbers (Jira, GitHub issues, or custom), ai-commit automatically extracts them from your branch name.

How it works

Name your branch after your ticket:

git checkout -b PROJ-12345-add-login-page

Then run ai-commit generate — it finds PROJ-12345 automatically:

✔ Ticket number found: PROJ-12345 — use it? ✅ Yes, use PROJ-12345

Generated commit message:
PROJ-12345 feat: add OAuth2 login with Google provider

If the ticket isn't in your branch name, it asks you to type it manually — or skip it entirely.

Supported formats

| Format | Example | Config | | ------------- | ------------ | ------------------------------------------------------- | | Jira style | PROJ-12345 | ticketFormat: "jira", ticketPrefix: "PROJ" | | GitHub issues | #123 | ticketFormat: "github" | | Custom regex | anything | ticketFormat: "custom", ticketRegex: "your-pattern" |

Set up ticket support with:

ai-commit init --local

Commands

| Command | Description | | ------------------------ | ------------------------------------------------- | | ai-commit init | Global setup wizard (API key, provider, defaults) | | ai-commit init --local | Per-project setup (generates .commitrc.json) | | ai-commit generate | Generate a commit message from staged changes |

Configuration

Global config (~/.ai-commit/config.json)

Set up once with ai-commit init. Works across all your projects.

{
  "provider": "gemini",
  "apiKey": "your_api_key",
  "commitTypes": ["feat", "fix", "docs", "style", "refactor", "test", "chore"],
  "requireScope": false,
  "maxLength": 72
}

Per-project config (.commitrc.json)

Generated by ai-commit init --local. Local config wins over global.

{
  "commitTypes": ["feat", "fix", "docs", "infra", "db"],
  "requireScope": true,
  "maxLength": 100,
  "ticketFormat": "jira",
  "ticketPrefix": "PROJ"
}

Commit this file to share conventions with your team.

Swapping AI Providers

Run ai-commit init again and select a different provider. Or edit ~/.ai-commit/config.json directly:

{
  "provider": "openai",
  "apiKey": "sk-..."
}

| Provider | Model | Notes | | -------- | ------------------------ | --------------------------------- | | gemini | gemini-2.5-flash | Free tier available — recommended | | openai | gpt-4o | Requires paid API access | | claude | claude-sonnet-4-20250514 | Requires paid API access |

How It Works

git add .
    ↓
ai-commit generate
    ↓
git diff --staged        ← reads your staged changes
    ↓
Diff Processor           ← filters lock files, binaries; truncates large diffs
    ↓
Ticket Extractor         ← finds ticket number from branch name (if configured)
    ↓
AI Provider              ← sends clean diff + your config to the AI
    ↓
Conventional commit      ← you confirm, edit, or cancel
    ↓
git commit -m "..."      ← committed!

Why process the diff before sending to AI? Lock files, binaries, and generated files are noise. A package-lock.json change adds thousands of lines that tell the AI nothing useful. The diff processor filters them out and truncates large files so you never hit token limits.

Contributing

PRs welcome. To add a new AI provider:

1. Create src/services/providers/myProvider.ts implementing AIProvider
2. Add a case in src/services/aiService.ts
3. Add it as a choice in src/commands/init.ts

Troubleshooting

Permission denied on install (Mac/Linux)

If you get an EACCES error when installing globally, either use sudo:

sudo npm install -g @julianabot/ai-commit

Or fix npm permissions permanently so you never need sudo for global installs:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Then install normally:

npm install -g @julianabot/ai-commit

Node version warning

If you see a warning about mute-stream requiring a newer Node version, update Node to v20.17.0 or higher:

# using nvm
nvm install 20.17.0
nvm use 20.17.0

License

MIT © julianabot