The smart way to write your commit messages using AI 🤖

GSmart is a CLI tool that automatically generates Conventional Commits by analyzing your staged git changes. Simply stage your files and let AI craft the perfect commit message for you.

✨ Features

• 🎯 Smart Commit Messages: AI-generated conventional commits based on your changes
• 🔄 Multiple AI Providers: Support for OpenAI, Anthropic, Google, Mistral, Fireworks AI, and PlataformIA
• 📋 Interactive CLI: Easy-to-use command line interface with interactive prompts
• 🧠 Rename-Aware Staging: Detects renames and copies so both sides get staged automatically
• 🔒 Secure: API keys stored locally and securely, validated before use
• ⏱️ Timeout Protection: Configurable request timeout prevents hanging on unresponsive APIs
• 🔁 Automatic Retries: Retries transient network errors with user feedback
• 🐛 Debug Mode: --debug flag for detailed logging and timing information
• 🧪 Dry Run: Preview staged files without committing using --dry-run
• ⚡ Fast: Quick analysis and generation of commit messages
• 📖 Conventional Commits: Follows industry-standard commit message format
• 🐚 Shell Completions: Tab completions for bash, zsh, and fish

🚀 Quick Start

Installation

Install GSmart globally using npm or pnpm:

# Using npm
npm install -g gsmart

# Using pnpm
pnpm add -g gsmart

# Using yarn
yarn global add gsmart

Setup

1. Configure your AI provider (one-time setup):

gsmart login

You'll be prompted to select a provider and enter your API key:

? Select a provider › Use arrow keys to navigate
❯ OpenAI
  Anthropic
  Google Gemini
  Mistral
  Fireworks AI
  PlataformIA

2. Generate commit messages:

# Stage your changes
git add .

# Generate and apply commit message
gsmart

That's it! GSmart will analyze your staged changes and generate a conventional commit message.

💡 Usage Examples

Basic Usage

# Stage some files
git add src/components/Button.tsx

# Generate commit message
gsmart
# Output: "feat(components): add Button component with primary and secondary variants"

Advanced Options

# Use a specific provider
gsmart --provider anthropic

# Use a custom prompt
gsmart --prompt "Focus on the security implications of these changes"

# Run non-interactively (auto-stage + commit if possible)
gsmart --yes

# Preview staged files without committing
gsmart --dry-run

# Enable debug logging for troubleshooting
gsmart --debug

# Show help
gsmart --help

Configuration

# Open the interactive configuration menu
gsmart config

# Set a default prompt that will be used on every run
gsmart config --add-custom-prompt "Always use imperative mood and mention the ticket number"

# Show the current default prompt
gsmart config --show

# Clear the default prompt
gsmart config --clear-custom-prompt

When --yes is set, GSmart stages all detected changes—including renames—and skips interactive prompts so you can automate message generation.

⚙️ Configuration

Environment Variables

Variable	Description	Default
GSMART_TIMEOUT	AI request timeout in milliseconds	30000

# Set a custom timeout (e.g., 60 seconds)
GSMART_TIMEOUT=60000 gsmart

If a request exceeds the timeout, GSmart exits cleanly with a user-friendly error message instead of hanging indefinitely.

📋 Command Reference

Usage: gsmart [options] [command]

CLI to generate smart commit messages using AI. generate command is the default command.

Options:
  -V, --version                    Output the version number
  -h, --help                       Display help for command

Commands:
  generate [options]               Generate a commit message based on staged changes (default)
    --provider <provider>          Use a specific AI provider
    --prompt <prompt>              Custom prompt for the AI model
    --yes                         Run non-interactively (auto stage + commit)
    --dry-run                     Preview staged files without committing
    --debug                       Enable debug logging and timing

  login                           Configure AI provider and API key
  reset                           Reset all API keys and configuration

  config [options]                Manage gsmart configuration (default prompt, commit style)
    -s, --show                    Show current configuration
    --add-custom-prompt <prompt>  Set the default prompt non-interactively
    --clear-custom-prompt         Clear the default prompt non-interactively

  completions <shell>             Output shell completion script (bash, zsh, or fish)

  help [command]                  Display help for command

🐚 Shell Completions

GSmart supports tab completions for bash, zsh, and fish. Run the completions command and add the output to your shell configuration:

Bash

Add to your ~/.bashrc:

eval "$(gsmart completions bash)"

Zsh

Add to your ~/.zshrc:

eval "$(gsmart completions zsh)"

Fish

gsmart completions fish > ~/.config/fish/completions/gsmart.fish

🤖 Supported AI Providers

Provider	Model	Get API Key
OpenAI	GPT-5 Codex	Get Key
Anthropic	Claude	Get Key
Google	Gemini 2.0 Flash	Get Key
Mistral	Mistral Large	Get Key
Fireworks AI	FireFunction V1	Get Key
PlataformIA	Radiance	Get Key

🧩 Skill for AI Agents

Do your AI agents write commits for you? Improve your commit quality with the write-conventional-commit skill.

Install it with:

npx skills add ragnarok22/agent-skills --skill write-conventional-commit

Repository: ragnarok22/agent-skills

🛠️ Development

Requirements

• Node.js 20+ with ESM support
• pnpm (recommended) or npm

Scripts

# Install dependencies
pnpm install

# Development mode
pnpm run dev

# Build the project
pnpm run build

# Run tests
pnpm test

# Lint code
pnpm run lint

# Format code
pnpm run format

Project Structure

src/
├── index.ts            # CLI entry point
├── gsmart.ts           # Command registration
├── definitions.ts      # Shared types and interfaces
├── build-info.ts       # Generated build metadata
├── commands/           # CLI command implementations
│   ├── main.ts         # Default command for commit message generation
│   ├── login.ts        # API key configuration
│   ├── reset.ts        # Configuration reset
│   ├── config.ts       # Custom prompt configuration (set, get, clear)
│   ├── completions.ts  # Shell completion script generator (bash, zsh, fish)
│   └── index.ts        # Command barrel export
└── utils/              # Reusable helpers
    ├── ai.ts           # AI provider integrations, retry handling, and timeout
    ├── config.ts       # Configuration and API key management
    ├── constants.ts    # Shared constants (defaults, timeouts)
    ├── debug.ts        # Debug logging utilities
    ├── git.ts          # Git operations
    ├── holiday.ts      # Seasonal greeting messages
    ├── index.ts        # File staging, clipboard, and retrieval logic
    ├── prompt-config.ts # Custom prompt persistence
    ├── providers.ts    # AI provider definitions and active-provider filter
    └── version-check.ts # Update notification via update-notifier

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes using GSmart! (gsmart)
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 Changelog

See CHANGELOG.md for details about releases and changes.

📝 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

---

_{Built with ❤️ by @ragnarok22}