AI Conventional Commit Generator

An intelligent VS Code extension that automatically generates conventional commit messages using AI. This extension analyzes your changes, whether staged or not, and creates properly formatted commit messages following the conventional commit specification.

Changes in log files, lock files, or environment files are never sent. Ensuring more efficient and secure commit generation.

Features

• AI-powered commit generation: uses the OpenAI model of your choice to analyze code changes and generate meaningful commit messages
• Conventional commit format: follows the conventional commit specification with proper type, scope, and description formatting
• Flexible configuration: supports both global extension settings and per-project configuration via ai-commit.json
• Language support: generates commit messages in the language you prefer
• Contextual analysis: analyzes file changes, git history, and project context for better commit messages
• Customizable output: controls emoji inclusion, scope, body content, and breaking changes as you prefer
• Model selection: automatically manages model availability and provides fallback options

Installation

1. Open VS Code
2. Go to Extensions
3. Search for AI Conventional Commit Generator
4. Click Install

Usage

1. Stage your changes using the Source Control panel
2. Click the blue Generate AI commit button
3. The extension will intelligently analyze your changes and generate a commit message in a few seconds
4. Review and modify the generated message if needed and commit your changes

Configuration

API Token via .env File

The extension now supports reading the OpenAI API token through a .env file in your project. This configuration takes priority over extension settings. Never use ai-commit.json to store private data.

Create a .env file in your project root:

AI_COMMIT_TOKEN=your_openai_api_key_here

Important: the .env file is automatically ignored by git to keep your credentials secure.

Project Configuration (ai-commit.json)

The extension prioritizes settings defined in the ai-commit.json file in your repository root. If it doesn't exist, it uses the global extension settings as fallback.

Create an ai-commit.json file in your repository root:

{
  "language": "English",
  "model": "gpt-5.4-mini",
  "modelReasoning": "medium",
  "types": {
    "feat": "new user-facing feature",
    "fix": "a bug fix",
    "docs": "documentation changes",
    "style": "code formatting and style",
    "refactor": "code restructuring without behavior changes",
    "tests": "adding or correcting tests",
    "chore": "routine maintenance and tooling"
  },
  "includeEmoji": true,
  "includeScope": true,
  "includeBody": true,
  "includeBreakingChange": true,
  "includeBreakingChangeExclamation": true,
  "additionalInstructions": "Focus on user-facing changes and performance improvements",
  "ignorePatterns": ["*.lock", "package-lock.json"],
  "scopes": {
    "ui": "user interface changes",
    "api": "API endpoint modifications",
    "core": "core framework or infrastructure changes"
  },
  "importantPatterns": ["**/*.php", "src/**/*.ts"],
  "contextLength": 3,
  "historyContextLength": 5,
  "template": "{%emoji }{%type}{ (%scope)}{%!}: %summary;{\n\n%body.}{\n\nBREAKING CHANGE: %breakingChange.}",
  "customEndpoint": "https://api.openai.com/v1/chat/completions"
}

Available Settings

All settings can be defined in ai-commit.json (priority) or in the global extension settings:

• language (default "English"): language that the summary and body will be generated in;
• model (default "gpt-5.4-mini"): OpenAI model that will be used to generate commit messages. More efficient models generate better messages and understand context better, but may incur higher usage costs;
• modelReasoning (default: "low"): model reasoning level. The default low usually generates very good quality, although it has a slightly higher cost than minimal;
• types (default: ["feat", "fix", "refactor", "docs", "tests", "style", "chore", "ci", "perf"]): list of allowed commit types in priority order. Accepts comma-separated string, array of names, or object with name→description pairs. Available only via ai-commit.json, not as a global extension setting;
• includeEmoji (default: false): indicates whether an emoji should be attached before the message type;
• includeScope (default: true): indicates whether the scope should be assigned after the type. The scope may not be generated in some cases where it might not make sense;
• includeBody (default: true): indicates whether the body (description beyond the summary) should be generated. In some cases, where the summary is sufficient, a body may not be generated;
• includeBreakingChange (default: true): indicates whether the breaking change message should be generated after the body when detected. You can allow it to be generated and edit the commit if you find it unnecessary. This way you stay aware of potential problems the update may cause;
• includeBreakingChangeExclamation (default: true): appends an exclamation mark to the type (or scope when present) whenever a breaking change is detected, following the conventional commit standard for major bumps;
• additionalInstructions: additional instructions that can be added to assist generation. For example, you can add context about what the project is about or even how you prefer commits to be generated;
• ignorePatterns: an array of strings containing globs to indicate files or folders that should be ignored and never sent for inference. By default, several patterns are already ignored, such as lock files, environment variables, and logs;
• scopes: pre-approved list of scopes the commit generator must choose from. Accepts comma-separated string, array of names, or object with name→description pairs. Empty means any scope is allowed;
• importantPatterns: an array of strings containing glob patterns for files that will be marked with an (important) tag in the diff output. This helps the AI identify important changes and give them more emphasis when generating commit messages. For example, in a PHP project, you might want **/*.php files to be marked as important over **/*.js files;
• contextLength (default: 5): to generate a message, inference receives a diff of modified files including some lines before and after what was actually modified. This provides more context for more efficient generation. The higher the context, the more information, but the cost also becomes higher. Usually a value between 3 and 10 is sufficient. Use 0 to disable, but this greatly reduces context and may generate slightly more erroneous information;
• historyContextLength (default: 10): sends your latest commit messages along to help inference generate something within the pattern you already like to use. It also gives a better sense of the change when they are sequential changes. The first commits will be sent with the complete message, including summary and body, and the rest will be sent only the summary. Use 0 to disable and save resources;
• template: custom template for the commit message output. Leave empty to use the default template. See the Output Template section for more details.
• customEndpoint (default: OpenAI): custom OpenAI API endpoint. Leave empty to use the default OpenAI API endpoint. Useful for using OpenAI-compatible APIs or custom deployments;

Output Template

The template controls how the final commit message is assembled. The default template is:

{%emoji }{%type}{ (%scope)}{%!}: %summary;{\n\n%body.}{\n\nBREAKING CHANGE: %breakingChange.}

Which generates something like:

✨ feat (Auth)!: add login;

Added OAuth2 login flow.

BREAKING CHANGE: removed legacy auth.

Supported Placeholders

Conditional Blocks

Wrap sections with {...} to create conditional blocks. The entire block disappears if any placeholder inside it resolves to empty.

For example, { (%scope)}:

• If scope is "Auth" → produces (Auth) (including the separator)
• If scope is "" → the entire block disappears, no leftover spaces or parentheses

Template Examples

Automatic Punctuation

The %summary, %body, and %breakingChange fields have trailing punctuation (. or ;) automatically removed. This allows the template to control punctuation. In the default template, ; is added after the summary and . after body and breakingChange.

Getting Started

1. Get an OpenAI API key:

   • Visit OpenAI API;
   • Create an API key;
   • Configure it in the extension settings.

2. Configure your preferences:

   • Set your preferred language, model, and output format;
   • Optionally create an ai-commit.json file for project-specific settings.

3. Start committing:

   • Stage your changes with git add or using the Source Control panel;
   • Use the blue Generate AI commit button in the Source Control panel.
   • Review and commit the generated message.

Troubleshooting

Common Issues

1. API Key Required: make sure you've configured your OpenAI API key in the extension settings;
2. Model unavailable: if the configured model isn't available, the extension will prompt you to select an alternative;
3. No changes detected: ensure you have staged changes before generating a commit message. If changes exist, these files might be ignored by the extension or project settings;
4. Permission errors: verify your OpenAI API key has the necessary permissions.

Support

For issues and feature requests, please visit the GitHub repository.

License

This extension is licensed under the Apache-2.0 License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.