Git Made Simple – AI‑powered git helper with smart insights, stats & code review
npm install gims




AI-powered Git CLI that writes your commit messages for you
Because life's too short for "fix stuff" commits 🎯
Installation • Quick Start • Commands • AI Setup • Configuration
---
- 🤖 AI-Generated Commits — Let AI analyze your changes and write meaningful commit messages
- 📊 Smart Status — Enhanced git status with file type detection and insights
- 🔄 Workflow Shortcuts — Common multi-step operations condensed to single commands
- 📈 Commit Analytics — Track your commit streak, patterns, and statistics
- 🔍 Code Review — Get AI-powered code review before committing
- 🛡️ Safe Operations — Built-in safeguards for destructive commands
- ⚡ Lightning Fast — Optimized for speed with intelligent caching
---
``bash`
npm install -g gims
Requirements: Node.js >= 18.18.0
---
`bash1. Setup AI provider (choose one)
g setup --api-key gemini # 🆓 Free & fast (recommended)
g setup --api-key openai # 🎯 High quality
g setup --api-key groq # ⚡ Ultra fast
$3
`bash
Before (traditional git)
git add .
git commit -m "trying to think of message..."
git pushAfter (with GIMS)
g o # That's it. AI handles the rest.
`---
📚 Commands
$3
| Command | Alias | Description |
|---------|-------|-------------|
|
g status | g s | Enhanced status with AI insights & file type emojis |
| g oneshot | g o | Stage all → AI commit → Push (full workflow) |
| g local | g l | Stage all → AI commit (no push) |
| g suggest | g sg | Get AI commit message suggestions |
| g version | g v | Manage project version (S4 system) |
| g whoami | — | Show system identity & version |
| g wip | — | Quick work-in-progress commit |$3
| Command | Alias | Description |
|---------|-------|-------------|
|
g review | g r | AI code review with complexity analysis |
| g today | g t | Show all commits made today |
| g stats | — | Personal statistics: streak, patterns, style |
| g split | — | AI suggestions for splitting large changesets |$3
| Command | Alias | What it does |
|---------|-------|--------------|
|
g safe-pull | g sp | Stash → Pull → Pop (safe pull with uncommitted changes) |
| g fix | — | Smart fix for diverged/ahead/behind branches |
| g main | — | Switch to main/master + pull latest |
| g stash-save | g ss | Quick stash with auto-generated name |
| g stash-pop | g pop | Pop the latest stash |
| g unstage | g us | Unstage all staged files |
| g discard | g x | Discard all changes (requires --yes) |$3
| Command | Alias | Description |
|---------|-------|-------------|
|
g last | — | Show last commit details with diff |
| g conflicts | — | Conflict resolution helper |
| g cleanup | g clean | Remove local branches deleted from remote |
| g list | g ls | Compact commit history |
| g amend | g a | Amend the previous commit |
| g undo | g u | Undo last commit (keep changes) |
| g delete-branch | g del | Delete branch locally and remotely |$3
GIMS now uses the S4 Versioning System, a forensic-grade versioning standard stored entirely in Git Tags.
MAJOR.MINOR.PATCH-STAGE.BUILD+DATE.TIME.COMMIT.BRANCH
(e.g., 0.8.2-dev.1+20250129.1305.af8d9c.main)| Command | Description |
|---------|-------------|
|
g v | Smart bump (resets build on new day) + Create Tag |
| g v -n | Dry run (preview next version) |
| g v major | Force major bump (1.0.0 → 2.0.0) |
| g v --list | List stable releases (hides dev tags) |
| g v --prune | Delete old dev tags (keeps last 10) |
| g v --undo | Undo last version bump (delete latest tag) |
| g v -i | Version analysis with timestamp |
| g whoami | Dynamic identity & version banner |> Note: S4 uses Git Tags as the Single Source of Truth. No
VERSION file is created. It updates your .env version variables if they exist.$3
| Command | Description |
|---------|-------------|
|
g setup | Interactive setup wizard |
| g setup --api-key | Quick API key setup |
| g config --list | View all settings |
| g config --set key=value | Update configuration |
| g quick-help / g q | Quick command reference |---
🤖 AI-Native Integration (New)
GIMS is designed to be "AI-Native", allowing AI agents to directly understand and control your git repository.
$3
GIMS includes a built-in MCP server. This allows AI assistants like Claude Desktop, Cursor, and VS Code to directly "see" and "use" GIMS tools.
#### Available Tools
-
get_status: Get AI-enhanced git status and insights.
- analyze_history: Analyze commit history and patterns.
- version_info: Get current S4 version details.
- generate_commit_message: Generate a commit message for staged changes.
- run_git_command: Safe execution of raw git commands.#### Usage with Claude Desktop
Add to your
claude_desktop_config.json:
`json
{
"mcpServers": {
"gims": {
"command": "node",
"args": ["/path/to/gims/mcp/index.js"]
}
}
}
`$3
If you are building your own AI agent (using OpenAI, LangChain, etc.), you can plug GIMS tools directly into your
tools array using our auto-generated schemas.Schema Location:
bin/tools-schema.json`javascript
const tools = require('gims/bin/tools-schema.json');
// Pass 'tools' directly to OpenAI API
`---
🤖 AI Providers
GIMS supports multiple AI providers. Choose based on your needs:
| Provider | Model | Speed | Quality | Cost |
|----------|-------|-------|---------|------|
| Gemini |
gemini-3-flash-preview | ⚡⚡⚡ | ⭐⭐⭐ | 🆓 Free |
| Groq | groq/compound | ⚡⚡⚡⚡ | ⭐⭐⭐ | 🆓 Free tier |
| OpenAI | gpt-5.2-2025-12-11 | ⚡⚡ | ⭐⭐⭐⭐ | 💰 Paid |$3
#### Option 1: Interactive Setup (Recommended)
`bash
g setup --api-key gemini # Guided setup with instructions
g setup --api-key openai
g setup --api-key groq
`#### Option 2: Environment Variables (Auto-detected)
GIMS automatically detects API keys from environment variables. Add to your shell profile (
~/.zshrc, ~/.bashrc, etc.):`bash
Gemini (recommended - free)
export GEMINI_API_KEY="your-api-key-here"OpenAI
export OPENAI_API_KEY="your-api-key-here"Groq
export GROQ_API_KEY="your-api-key-here"
`Then reload your shell:
source ~/.zshrc> 💡 Tip: If multiple API keys are set, GIMS auto-selects in order: Gemini → OpenAI → Groq
$3
🔷 Gemini (Recommended)
1. Visit Google AI Studio
2. Create a new API key
3. Set it:
export GEMINI_API_KEY="your-key" or run g setup --api-key gemini
🟢 Groq
1. Visit Groq Console
2. Create a new API key
3. Set it:
export GROQ_API_KEY="your-key" or run g setup --api-key groq
🟡 OpenAI
1. Visit OpenAI Platform
2. Create a new API key
3. Set it:
export OPENAI_API_KEY="your-key" or run g setup --api-key openai---
🔧 Configuration
`bash
View current settings
g config --listEnable conventional commits (feat:, fix:, etc.)
g config --set conventional=trueAuto-stage all changes before commit
g config --set autoStage=trueDisable clipboard copy
g config --set copy=falseShow/hide progress indicators
g config --set progressIndicators=true
`$3
| Option | Type | Default | Description |
|--------|------|---------|-------------|
|
provider | string | auto | AI provider: gemini, openai, groq, auto, none |
| model | string | — | Override default model for provider |
| conventional | boolean | false | Use Conventional Commits format |
| autoStage | boolean | false | Auto-stage all changes |
| copy | boolean | true | Copy suggestions to clipboard |
| progressIndicators | boolean | true | Show progress spinners |---
📖 Usage Examples
$3
`bash
g s # Check what's changed
g sp # Safe pull (won't lose uncommitted work)
... do your work ...
g o # Commit everything with AI message + push
`$3
`bash
g r # Get AI review of your changes
g o # Commit if review looks good
`$3
`bash
g fix # See sync status and options
g fix --ai # Get AI recommendation
g fix --merge # Merge remote changes
g fix --rebase # Rebase onto remote
`$3
`bash
g ss # Quick stash
g main # Switch to main and pull
... check something ...
g pop # Get your work back
`$3
`bash
g split # Get suggestions for splitting changes
g sg --multiple # Get multiple commit message options
`---
🆚 GIMS vs Plain Git
| Task | Git | GIMS |
|------|-----|------|
| Commit & push |
git add . && git commit -m "msg" && git push | g o |
| Pull with uncommitted changes | git stash && git pull && git stash pop | g sp |
| Check status | git status | g s (+ AI insights) |
| Fix diverged branch | Multiple commands + decisions | g fix --ai |
| Code review | External tool | g r |---
🆘 Getting Help
`bash
g --help # Full command list with descriptions
g q # Quick reference card
g -h # Help for specific command
``---
Contributions are welcome! Feel free to:
- 🐛 Report bugs
- 💡 Suggest features
- 🔧 Submit pull requests
---
MIT © S41R4J
---
Made with ❤️ for developers who'd rather code than write commit messages