AI-powered commit message generator for git
npm install @light-cat/ai-commit-msgAI-powered commit message generator for git. Automatically generates conventional commit messages based on your staged changes.
- 🤖 AI-powered: Uses AI to analyze your code changes and generate meaningful commit messages
- 📝 Conventional Commits: Follows the Conventional Commits format
- 🔧 Easy Configuration: Simple .env setup with environment variable support
- 🛡️ Safe: Doesn't block commit on errors - falls back gracefully
- 🔌 OpenAI Compatible: Works with OpenAI, Azure OpenAI, and any OpenAI-compatible API
- ⚡ CLI Ready: Can be used directly with pnpm exec or installed globally
``bashWith npm
npm install --save-dev @light-cat/ai-commit-msg
$3
`bash
With npm
npm install -g @light-cat/ai-commit-msgWith pnpm
pnpm add -g @light-cat/ai-commit-msgThen set up git hooks in your project
cd /path/to/your/project
pnpm exec ai-commit setup
`Configuration
Create a
.env file in your project root or set environment variables:`env
Required
AI_API_KEY=your-api-key-hereOptional (defaults shown)
AI_API_BASE_URL=https://api.openai.com/v1
AI_MODEL=gpt-4
`$3
| Provider |
AI_API_BASE_URL | AI_MODEL |
|----------|-------------------|------------|
| OpenAI | https://api.openai.com/v1 | gpt-4, gpt-3.5-turbo |
| Azure OpenAI | Your Azure endpoint | Your deployment name |
| Local/Other | Your custom endpoint | Any OpenAI-compatible model |$3
- OpenAI: Get your API key from platform.openai.com
Usage
$3
After setting up the git hook, simply commit your changes without providing a message:
`bash
Stage your changes
git add .Commit - AI will automatically generate a commit message
git commit
`The tool will:
1. Fetch staged changes
2. Send them to the AI service
3. Generate a conventional commit message
4. Write it to the commit message file
$3
`bash
Install hooks and configure simple-git-hooks automatically
pnpm exec ai-commit setup
`$3
Add to your
package.json:`json
{
"simple-git-hooks": {
"prepare-commit-msg": "pnpm exec ai-commit"
}
}
`Or if using
lefthook:`yaml
lefthook.yml
pre-commit:
commands:
generate-commit-msg:
run: pnpm exec ai-commit
`$3
`bash
Dry run (show message without writing)
pnpm exec ai-commit --dry-runVerbose mode (show debug info)
pnpm exec ai-commit --verboseHelp
pnpm exec ai-commit --help
`How It Works
1. When you run
git commit, the prepare-commit-msg hook is triggered
2. The tool fetches:
- Staged changes (git diff --cached)
- Current branch name
- Last commit message (if available)
3. Sends this information to the AI service
4. Generates a conventional commit message
5. Writes it to the commit message fileExample
Given this staged change:
`diff
diff --git a/src/auth.ts b/src/auth.ts
+export function validateEmail(email: string): boolean {
+ return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
`The tool might generate:
`
feat(auth): add email validation function
`Troubleshooting
$3
Make sure your
.env file exists and contains AI_API_KEY, or set the environment variable before committing.$3
1. Check if changes are staged (
git add first)
2. Run with --verbose to see debug information
3. Ensure your API key has sufficient credits/permissions
4. Verify git hooks are installed: cat .git/hooks/prepare-commit-msg$3
Simply provide a commit message when running
git commit -m "your message" - the tool will detect an existing message and skip generation.Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Local Development
$3
#### 1. Direct Source Execution
Run the source code directly with
tsx (recommended for ESM projects):`bash
cd /path/to/node-ai-commit
pnpm tsx bin/ai-commit.js --help
`Or using the dev script:
`bash
pnpm dev -- --help
`> Note:
ts-node has limited ESM support. Use tsx instead for better compatibility.#### 2. Using npm link
Link the local package globally and test in other projects:
`bash
cd /path/to/node-ai-commit
pnpm linkIn another project
cd /path/to/your-project
pnpm link @light-cat/ai-commit-msg
pnpm exec ai-commit setup
`#### 3. Local Path Installation
In another project's
package.json:`json
{
"devDependencies": {
"@light-cat/ai-commit-msg": "link:/path/to/node-ai-commit"
}
}
`Then run
pnpm install or npm install in that project.#### 4. Build and Test
`bash
Build the TypeScript
pnpm buildRun locally (requires build first)
node bin/ai-commit.js --helpOr run directly without building
pnpm tsx bin/ai-commit.js --help
`$3
1. Create a test repository:
`bash
mkdir test-ai-commit && cd test-ai-commit
git init
`2. Link the local package:
`bash
cd /path/to/node-ai-commit
pnpm link --globalcd /path/to/test-ai-commit
pnpm link --global @light-cat/ai-commit-msg
`3. Set up and test:
`bash
Create .env with your API key
pnpm exec ai-commit setupMake some changes and commit (don't provide message, let AI generate it)
git add .
git commit
``