NeuroCommit is a CLI tool that analyzes your staged Git changes and generates commit messages — either automatically via OpenAI API or as a structured prompt you can paste into any LLM.

Table of Contents

• Features
• Quick Start
• How It Works
• Configuration
• Development
• Contributing
• Security
• License
• Star History

✨ Features

• AI Commit mode — generates and commits messages automatically using OpenAI API (gpt-5-nano) with Structured Outputs
• Manual mode — saves a prompt to neuro-commit.md for pasting into any LLM (ChatGPT, Claude, etc.)
• Conventional Commits — always uses feat:, fix:, docs:, refactor:, etc.
• Smart lock file handling — detects lock files and omits their noisy diffs
• Minimal UI — clean terminal interface, no visual clutter
• Multi-language — commit message body in English, Ukrainian, Russian, German, French, or Spanish
• Configurable — auto-commit, auto-push, commit history context, dev mode
• Secure — API key via environment variable only, no shell injection vectors

🚀 Quick Start

Using npx (No Installation Required)

npx neuro-commit

Global Installation

npm install -g neuro-commit

Then run:

neuro-commit

Setting up OpenAI API Key

For AI Commit mode, set your API key:

# Linux / macOS
export OPENAI_API_KEY="sk-..."

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-..."

# Windows CMD
set OPENAI_API_KEY=sk-...

📖 How It Works

AI Commit Mode

1. Stage your changes with git add
2. Run neuro-commit → select AI Commit
3. Review the file summary and confirm generation
4. The tool sends your diff to OpenAI API and generates a commit message
5. Choose: Commit, Edit, Regenerate, or Cancel

Manual Mode

1. Stage your changes with git add
2. Run neuro-commit → select Manual Mode
3. A neuro-commit.md file is generated with the full prompt
4. Paste into your preferred LLM and get a commit message

Both modes use the same prompt — the only difference is delivery method.

⚙️ Configuration

Settings are stored in ~/.neurocommit/config.json. Access via the Settings menu.

| Setting | Default | Description | | -------------- | ------- | -------------------------------------- | | Language | en | Commit message body language | | Max length | 72 | Title character limit | | Auto-commit | OFF | Commit immediately after generation | | Auto-push | OFF | Push after committing | | Commit history | 5 | Recent commits included as AI context | | Dev mode | OFF | Store API responses (OpenAI dashboard) |

🔧 Development

# Clone the repository
git clone https://github.com/cr1ma/neuro-commit.git
cd neuro-commit

# Install dependencies
npm install

# Run locally
npm start

# Lint
npm run lint

# Lint & auto-fix
npm run lint:fix

🤝 Contributing

Contributions, issues, and feature requests are welcome! Please read the Contributing Guide before submitting a pull request.

Feel free to check the open issues.

🔒 Security

To report a vulnerability, please see our Security Policy.

📝 License

This project is licensed under the Apache License 2.0.

⭐ Star History