npm package: @julianabot/ai-commit
Description: Free AI-powered conventional commit message generator using Gemini Flash as default
Author: julianabot
Latest version: 1.1.7

# 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.

---

![ai-commit demo](https://s13.gifyu.com/images/bm0Ka.gif)

---

## 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

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

---

## Getting Started

### 1. Install

```bash
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

```bash
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

```bash
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

```bash
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:

```bash
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:

```bash
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.

```json
{
  "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.

```json
{
  "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:

```json
{
  "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`:

```bash
sudo npm install -g @julianabot/ai-commit
```

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

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

Then install normally:

```bash
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:

```bash
# using nvm
nvm install 20.17.0
nvm use 20.17.0
```

---

## License

MIT © [julianabot](https://github.com/julianabot)