commitment

AI-powered commit message generator using your local CLI tools - no API keys required

We all know we should write better commit messages. But we don't.

commitment uses your local AI CLI (Claude Code, Codex, or Gemini) to analyze git diffs and generate professional, conventional commit messages automatically. No API keys or additional services required - it works with the AI tools you already have installed.

Features

• 🤖 No API keys required - Uses Claude Code, Codex, or Gemini CLI tools you already have installed (no additional setup or services)
• 📖 Context-aware - Agentic coding CLIs understand your codebase context beyond just the diff
• 🎯 Conventional Commits - Every commit follows Conventional Commits format
• 🚀 Frictionless setup - One command (commitment init) and stop committing wip2 and formatting
• 🪝 Hook integration - Works with lefthook, husky, simple-git-hooks, or plain git hooks

Quick Start

Local Install (Recommended)

# 1. Install in your project
npm install -D @arittr/commitment

# 2. Set up git hooks (automatic)
npx commitment init

# 3. Make changes and commit
git add .
git commit  # Message generated automatically!

Global Install

# 1. Install globally
npm install -g @arittr/commitment

# 2. Set up git hooks in any project
cd /path/to/your/project
commitment init

# 3. Make changes and commit
git add .
git commit  # Message generated automatically!

That's it! Every commit now gets an AI-generated, pretty good commit message.

Installation

Local (Per-Project)

# Using npm
npm install -D @arittr/commitment
# Run with: npx commitment

# Using pnpm
pnpm add -D @arittr/commitment
# Run with: pnpm exec commitment

# Using yarn
yarn add -D @arittr/commitment
# Run with: yarn commitment

# Using bun
bun add -D @arittr/commitment
# Run with: bun commitment

Global (System-Wide)

npm install -g @arittr/commitment
# Run with: commitment

One-Off (No Install)

# Try without installing
npx @arittr/commitment --dry-run

Note: Use full package name @arittr/commitment for one-off runs, but just commitment when installed locally/globally.

Requirements

• Node.js >= 18
• Git repository
• AI CLI (one of):
  • Claude CLI (recommended) - Install with npm install -g @anthropic-ai/claude-code
  • Codex CLI - Install with npm install -g @openai/codex
  • Gemini CLI - Install with npm install -g @google/gemini-cli

[!IMPORTANT] commitment uses your local AI CLI tools (not the OpenAI API or other cloud services). You need one of the CLIs above installed and configured.

Usage

Note: Examples below use npx commitment (local install). If installed globally, use commitment instead.

Automatic (Recommended)

After running npx commitment init, commit messages are generated automatically:

git add src/components/Button.tsx
git commit  # Opens editor with AI-generated message

Manual

Generate a message and commit in one step:

git add .
npx commitment

Generate message only (preview without committing):

npx commitment --dry-run

Use a specific AI agent:

npx commitment --agent codex
# or
npx commitment --agent gemini

How It Works

1. Analyze: Reads your staged changes with git diff --cached
2. Generate: Sends diff to AI CLI with a detailed prompt
3. Validate: Ensures response follows Conventional Commits format
4. Commit: Creates commit with generated message

Example

git add src/api/ src/types/
npx commitment

Generated:

test: update test naming conventions and mock patterns

- Rename runner tests to reflect unit vs integration scope
- Update base-agent tests to use `command -v` instead of `which`
- Fix mock expectations to require non-empty stdout for availability checks
- Reorganize markdown reporter tests to use timestamped directories
- Add responseTimeMs validation to eval runner tests
- Update CLI invocation mocks to use shell wrapper pattern

🤖 Generated with Claude via commitment

Configuration

CLI Options

| Option | Description | Default | |--------|-------------|---------| | --agent <name> | AI agent to use (claude, codex, or gemini) | claude | | --dry-run | Generate message without creating commit | false | | --message-only | Output only the commit message (implies --quiet) | false | | --quiet | Suppress progress messages (useful for scripting) | false | | --cwd <path> | Working directory | current directory |

Examples:

# Use Gemini agent
npx commitment --agent gemini

# Preview message without committing
npx commitment --dry-run

# Suppress progress messages (for scripts)
npx commitment --quiet

See docs/CLI.md for complete CLI reference.

Hook Setup

commitment supports multiple hook managers:

| Manager | Command | Best For | |---------|---------|----------| | Auto-detect | npx commitment init | Most projects | | Lefthook | npx commitment init --hook-manager lefthook | Fast, parallel execution, YAML config (recommended) | | Husky | npx commitment init --hook-manager husky | Teams with existing husky setup | | simple-git-hooks | npx commitment init --hook-manager simple-git-hooks | Lightweight alternative | | Plain Git Hooks | npx commitment init --hook-manager plain | No dependencies |

Configure default agent:

npx commitment init --agent gemini  # Use Gemini by default
npx commitment init --agent codex   # Use Codex by default

See docs/HOOKS.md for detailed hook integration guide.

Troubleshooting

Hooks Not Running

Check installation:

# For lefthook
cat lefthook.yml

# For husky
ls -la .husky/prepare-commit-msg

# For plain git hooks
ls -la .git/hooks/prepare-commit-msg

Reinstall:

npx commitment init

Check permissions (Unix-like systems):

# For lefthook, run:
npx lefthook install

# For husky
chmod +x .husky/prepare-commit-msg

# For plain git hooks
chmod +x .git/hooks/prepare-commit-msg

Hooks Override My Custom Messages

This should not happen. Hooks check if you've specified a message:

git commit -m "my message"  # Uses your message ✅
git commit                  # Generates message ✅

If hooks override your messages, please file an issue.

Windows Issues

Symptoms:

• Hooks don't run
• Line ending errors (\r in scripts)

Solutions:

1. Use Git Bash or WSL instead of CMD/PowerShell

2. Verify line endings - commitment init handles this automatically

3. Check git config:

   git config core.autocrlf false

Cross-Platform Support

| Platform | CLI Usage | Hooks | AI Agents | |----------|-----------|-------|-----------| | macOS | ✅ | ✅ | ✅ Claude, Codex, Gemini | | Linux | ✅ | ✅ | ✅ Claude, Codex, Gemini | | Windows | ✅ | ⚠️ Git Bash/WSL | ✅ Claude, Codex, Gemini |

Note: Windows users should use Git Bash or WSL for best hook compatibility.

Contributing

Contributions welcome!

For Contributors

Requirements:

• Bun 1.1.0+ (development, bundling, testing)

Development:

# Install dependencies
bun install

# Run tests
bun test

# Run linting
bun run lint

# Build
bun run build

# Run evaluation system
bun run eval

Adding a New AI Agent:

See CLAUDE.md for detailed instructions.

Architecture:

This project follows a strict layered architecture with schema-first type safety. See docs/constitutions/current/ for:

• Architecture guidelines
• Testing patterns
• Type safety rules
• Code style requirements

Evaluation System

commitment includes a comprehensive evaluation framework that compares AI agents using multi-attempt testing:

# Run full evaluation
bun run eval

# Test specific fixture
bun run eval:fixture simple

# Test with live git changes
bun run eval:live

Results are saved to .eval-results/ with:

• Per-attempt scores and metrics
• Meta-evaluation across attempts
• Success rates and consistency analysis
• Response time measurements

This is not part of the test suite - it's a standalone tool for evaluating agent quality.

License

ISC

Acknowledgments

• Follows Conventional Commits specification
• Built with Claude CLI, Zod, and Bun
• Developed using Spectacular and Superpowers for Claude Code
• Inspired by years of bad commit messages