@elsikora/commitizen-plugin-commitlint-ai
Advanced tools
AI-powered Commitizen adapter with Commitlint integration
Transform your Git workflow with AI-powered commit messages that follow conventional standards and pass Commitlint validation every time
Commitizen Plugin Commitlint AI revolutionizes the way developers write commit messages by combining the power of artificial intelligence with strict conventional commit standards. Built with clean architecture principles, this plugin seamlessly integrates with your existing Commitizen workflow to generate meaningful, context-aware commit messages that adhere to your project's Commitlint rules.
Whether you're working on a solo project or collaborating in a large team, this tool eliminates the cognitive overhead of crafting perfect commit messages while maintaining a consistent, high-quality Git history. It supports multiple AI providers including OpenAI's GPT-4.1, Anthropic's Claude 4, Google's Gemini 2.5, and even local models through Ollama.
The plugin intelligently analyzes your staged changes, understands the context of your modifications, and generates commit messages that not only follow the conventional format but also provide meaningful descriptions of the changes. With automatic validation and smart retry mechanisms, it ensures every commit message meets your project's standards.
# Install the plugin as a dev dependency
npm install --save-dev @elsikora/commitizen-plugin-commitlint-ai
# Initialize Commitizen with this adapter
npx commitizen init @elsikora/commitizen-plugin-commitlint-ai --save-dev --save-exact
# Install Commitlint (if not already installed)
npm install --save-dev @commitlint/cli @commitlint/config-conventional
# Create a commitlint config file
echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js
# Stage your changes
git add .
# Run the AI-powered commit wizard
git cz
# or
npm run commit
The plugin supports multiple configuration approaches:
# .env file
OPENAI_API_KEY=sk-...
# or
ANTHROPIC_API_KEY=sk-ant-...
# or
GOOGLE_API_KEY=AIza...
# or (Azure OpenAI)
AZURE_OPENAI_API_KEY=https://your-resource.openai.azure.com|your-api-key|your-deployment-name
# or (AWS Bedrock)
AWS_BEDROCK_API_KEY=us-east-1|access-key-id|secret-access-key
# or (Ollama)
OLLAMA_API_KEY=localhost:11434|llama3.2
Create .elsikora/commitlint-ai.config.js:
export default {
provider: 'openai',
model: 'gpt-4.1',
mode: 'auto',
maxRetries: 3,
validationMaxRetries: 3
};
{
"elsikora": {
"commitlint-ai": {
"provider": "anthropic",
"model": "claude-opus-4-20250514",
"mode": "auto"
}
}
}
The AI analyzes your changes and generates appropriate commit messages:
$ git cz
✔ Using AI-powered commit mode...
✔ AI generated initial commit message
✔ AI generated commit message successfully!
┌─────────────────────────────────┐
│ Generated commit message: │
├─────────────────────────────────┤
│ feat(auth): implement OAuth2 │
│ │
│ Added OAuth2 authentication │
│ flow with JWT token support. │
│ Includes refresh token logic │
│ and secure session management. │
│ │
│ BREAKING CHANGE: Auth API │
│ endpoints have been updated │
└─────────────────────────────────┘
✔ Do you want to proceed with this commit message? (Y/n)
Guided commit message creation with validation:
$ git cz
✔ Using manual commit mode...
? Select commit type: (Use arrow keys)
❯ feat: A new feature ✨
fix: A bug fix 🐛
docs: Documentation only changes 📚
style: Code style changes 🎨
refactor: Code refactoring 📦
perf: Performance improvements 🚀
test: Adding tests 🚨
? Enter scope (optional): auth
? Enter commit subject: add login functionality
? Enter commit body (optional):
? Is this a breaking change? No
Provide project-specific guidance to the AI:
// commitlint-ai.config.js
export default {
provider: 'openai',
model: 'gpt-4.1',
instructions: 'Focus on business impact and user-facing changes. Use present tense.'
};
export default {
maxRetries: 5, // AI generation retries
validationMaxRetries: 3 // Validation fix attempts
};
Azure OpenAI:
AZURE_OPENAI_API_KEY=https://myresource.openai.azure.com|api-key|gpt-4-deployment
AWS Bedrock:
AWS_BEDROCK_API_KEY=us-west-2|AKIAIOSFODNN7EXAMPLE|wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Ollama (Local):
# Default setup
OLLAMA_API_KEY=localhost:11434
# Custom model
OLLAMA_API_KEY=localhost:11434|codellama
The plugin respects all your Commitlint rules:
// commitlint.config.js
export default {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor']],
'scope-case': [2, 'always', 'lower-case'],
'subject-max-length': [2, 'always', 72],
'body-max-line-length': [2, 'always', 100]
}
};
# Create manual mode marker
mkdir -p .elsikora
touch .elsikora/manual
rm -rf .elsikora/commitlint-ai.config.*
DEBUG=commitizen-ai git cz
| Task / Feature | Status |
|---|---|
| Core AI-powered commit generation | ✅ Done |
| Multi-provider support (OpenAI, Anthropic, Google) | ✅ Done |
| Commitlint rule integration | ✅ Done |
| Clean architecture implementation | ✅ Done |
| Automatic validation and fixing | ✅ Done |
| Environment variable support | ✅ Done |
| Cosmiconfig integration | ✅ Done |
| Interactive mode switching | ✅ Done |
| Breaking change detection | ✅ Done |
| AWS Bedrock and Azure OpenAI support | ✅ Done |
| Local Ollama model support | ✅ Done |
| Custom prompt templates | 🚧 In Progress |
| Multi-language commit messages | 🚧 In Progress |
| Git hook integration | 🚧 In Progress |
| VS Code extension | 🚧 In Progress |
| Team collaboration features | 🚧 In Progress |
| Commit message analytics | 🚧 In Progress |
| GitHub Copilot integration | 🚧 In Progress |
| Performance optimizations for monorepos | 🚧 In Progress |
Q: Which AI providers are supported? A: The plugin supports OpenAI (GPT-4.1, GPT-4o), Anthropic (Claude 4, Claude 3.5), Google (Gemini 2.5), Azure OpenAI, AWS Bedrock, and local Ollama models. Each provider offers different models optimized for various use cases.
Q: How does the AI understand my code changes? A: The plugin analyzes your git diff, staged files, and file paths to understand the context. It then uses this information along with your Commitlint rules to generate appropriate conventional commit messages.
Q: Is my code sent to AI services? A: Only the git diff and file names are sent to generate accurate commit messages. Full source code files are not transmitted unless they appear in the diff. For sensitive projects, consider using Ollama for local processing.
Q: What happens if the AI service is unavailable? A: The plugin has a configurable retry mechanism with real-time status updates. If all retries fail, it automatically falls back to the guided manual mode, ensuring you can always create commits.
Q: Can I customize the commit message format? A: Yes! The plugin fully respects your Commitlint configuration. You can define custom types, scopes, and rules. Additionally, you can provide custom instructions to guide the AI's generation style.
Q: How do I switch between AI and manual modes?
A: When you run git cz, you'll be prompted to choose your mode. You can also set a default mode in the configuration or create a .elsikora/manual file to force manual mode.
Q: Is it safe to store API keys? A: The plugin prioritizes security by reading API keys from environment variables. Keys are never stored in configuration files. For added security, you can also input keys per session.
Q: Can I use this with my existing Commitizen setup? A: Absolutely! This is a drop-in replacement for other Commitizen adapters. It works seamlessly with your existing Commitlint configuration and Git workflow.
Q: What's the difference between generation and validation retries?
A: Generation retries (maxRetries) handle AI service failures, while validation retries (validationMaxRetries) attempt to fix commit messages that don't pass Commitlint rules.
Q: How much does it cost to use? A: The plugin itself is free and open-source. You'll need to pay for API usage with your chosen AI provider, or use free local models with Ollama.
This project is licensed under MIT License - see LICENSE file for details.
2.0.1 (2025-06-04)
Implemented comprehensive LLM provider support with clean architecture principles. Added four new LLM service implementations:
Each provider includes:
Updated configuration system to support provider-specific settings. Enhanced documentation with detailed setup instructions for each provider.
This commit refactors the entire codebase to use ESM modules instead of CommonJS. Key changes include:
Additionally, this commit includes dependency updates and improvements to the overall code structure for better maintainability.
Restructured the entire codebase to follow clean architecture principles and domain-driven design patterns. This major refactoring improves code organization, testability, and maintainability.
Key changes:
This refactoring maintains all existing functionality while providing a more scalable and maintainable foundation for future development.
Replaced the inquirer dependency with a custom prompts interface built on top of the prompts library. This change provides a more consistent and maintainable API for handling user prompts throughout the application.
Key changes:
FAQs
AI-powered Commitizen adapter with Commitlint integration
The npm package @elsikora/commitizen-plugin-commitlint-ai receives a total of 149 weekly downloads. As such, @elsikora/commitizen-plugin-commitlint-ai popularity was classified as not popular.
We found that @elsikora/commitizen-plugin-commitlint-ai demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.
Security News
This episode explores the hard problem of reachability analysis, from static analysis limits to handling dynamic languages and massive dependency trees.
Security News
/Research
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.