GSmart - Commits Inteligentes com IA
ragnarok22/gsmart
Gera commits em Conventional Commits automaticamente com IA
Ver no GitHubCLI que gera automaticamente mensagens de commit seguindo Conventional Commits ao analisar suas mudanças staged no Git. Integra múltiplos provedores de IA (OpenAI, Anthropic, Google, Mistral, Fireworks, PlataformIA) com interface interativa, retry automático e validação segura de chaves.
Instalação
npx convez-ai ragnarok22/gsmart1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Padronizar mensagens de commit em equipes
- Agilizar workflow de commits em desenvolvimento local
- Manter histórico Git estruturado e pesquisável
Veredito

Ferramenta prática que resolve um problema real de workflow Git. Implementação sólida com suporte a múltiplos provedores, retry automático e modo debug, mas exige integração local e configuração inicial de chaves de API.
README
A tradução para o português deste README ainda está na fila.
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:
--debugflag 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
- Configure your AI provider (one-time setup):
gsmart login
You'll be prompted to select a provider. OpenAI supports either ChatGPT subscription login or an API key; other providers ask for an API key:
? Select a provider › Use arrow keys to navigate
❯ OpenAI
Anthropic
Google Gemini
Mistral
Fireworks AI
PlataformIA
If you are developing locally, do not run pnpm login or npm login; those commands authenticate with the npm registry. Use pnpm exec tsx src/index.ts login or build first and run node dist/index.js login.
- 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 authentication
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 |
| 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
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes using GSmart! (
gsmart) - Push to the branch (
git push origin feature/amazing-feature) - 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.
Contributors
Star History
View star history on Star History