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
  -D, --debug                      Enable debug logging and timing
  -h, --help                       Display help for command

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

  login                            Configure AI provider and API key
  reset [options]                  Reset all API keys and configuration
    -f, --force                    Force reset without confirmation prompt

  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 with Commander.js and signal handling
├── gsmart.ts           # Command registration and wiring
├── definitions.ts      # Shared types and interfaces
├── build-info.ts       # Generated build metadata
├── types/
│   └── conf.d.ts       # Module type declaration for conf
├── 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, retries)
    ├── 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
    └── welcome.ts      # First-run welcome with shell completion instructions

🤝 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.