commitaj

AI-powered commit messages that actually make sense.

Stage your changes, run commitaj, and get Conventional Commit messages generated by AI — ready to commit in seconds.

✨ Features

• 🤖 AI-Powered — Analyzes your staged diff and generates precise, context-aware commit messages
• 📐 Conventional Commits — Every message follows the Conventional Commits spec (feat, fix, refactor, etc.)
• 🎯 2 Suggestions — Get a short & punchy option and a detailed option with body
• 🔧 Any Model — Use any model on OpenRouter — free or paid
• 🧠 Context-Aware — Detects your framework, branch, affected modules, and change category
• 📝 Edit Before Committing — Inline editing or open in your preferred external editor
• 🚀 Non-Interactive Mode — Use --no-interactive for CI/CD pipelines and automation
• ⚡ Lightweight — Only 5 runtime dependencies. Installs in seconds.
• 🔒 Secure — API key stored locally via OS-native config. Never committed to git.

📦 Installation

npm install -g commitaj

Requires Node.js 18+ and git installed.

🚀 Quick Start

# 1. Set up your API key (free — no credit card needed)
commitaj init

# 2. Stage your changes
git add .

# 3. Generate a commit message
commitaj

That's it! commitaj will analyze your diff, generate two suggestions, and let you pick, edit, or regenerate.

⚙️ Configuration

Setup Wizard

commitaj init

The interactive wizard walks you through:

1. API Key — Get your free key at openrouter.ai/keys
2. Model Selection — Pick from recommended free models or enter any custom model ID

Manual Configuration

# Set your API key
commitaj config set apiKey sk-or-v1-...

# Set the AI model
commitaj config set model openai/gpt-4o-mini

# View current config
commitaj config list

# Get a specific value
commitaj config get model

# Reset to defaults
commitaj config reset

Environment Variables

You can also set your API key via environment variable:

export OPENROUTER_API_KEY="sk-or-v1-..."

Environment variables take precedence over stored config.

📖 Usage

Interactive Mode (Default)

# Generate commit messages for staged changes
commitaj

# Override the AI model for a single run
commitaj --model anthropic/claude-sonnet-4

# Dry run — preview the message without committing
commitaj --dry

Non-Interactive Mode

Perfect for CI/CD pipelines, scripts, and automation:

# Auto-select first suggestion and commit
commitaj --no-interactive

# Preview message without committing (pipeable)
commitaj --no-interactive --dry

# Combine with custom model
commitaj --no-interactive --model openai/gpt-4o-mini

Non-interactive mode is auto-detected when stdin is not a TTY (e.g., in CI/CD).

Commands

| Command | Description | |---------|-------------| | commitaj | Generate AI commit message (default) | | commitaj init | Interactive setup wizard | | commitaj config <action> | Manage configuration (set, get, list, reset) | | commitaj --help | Show help | | commitaj --version | Show version |

Flags

| Flag | Description | |------|-------------| | --dry | Preview message without committing | | --model <id> | Override AI model for this run | | --no-interactive | Auto-commit without prompts | | --help | Show help | | --version | Show version |

🤖 Model Support

commitaj uses OpenRouter to access AI models. You can use any model available on OpenRouter — free or paid.

Default Models (Free)

| Model | Role | Description | |-------|------|-------------| | openai/gpt-oss-120b:free | Primary | Thinking model — high quality | | z-ai/glm-4.5-air:free | Fallback | Fast fallback if primary fails |

Custom Models

Use any OpenRouter model by setting it via config or CLI flag:

# Via config (persistent)
commitaj config set model anthropic/claude-sonnet-4

# Via CLI flag (one-time)
commitaj --model google/gemini-2.5-flash

Browse all available models at openrouter.ai/models.

🔄 CI/CD Integration

GitHub Actions

- name: AI Commit
  env:
    OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
  run: |
    git add .
    npx commitaj --no-interactive

🏗️ How It Works

1. Reads your staged diff — git diff --cached
2. Filters noise — Strips lockfiles, build output, images, etc.
3. Enriches context — Detects framework, branch, affected modules, change category
4. Sends to AI — Formatted diff + context → OpenRouter API
5. Parses response — Extracts Conventional Commit messages from AI output
6. Presents options — Two suggestions: short & punchy vs. detailed with body
7. Commits — Your choice, edited or as-is

📝 License

MIT © AJ