gims

<div align="center"> <!-- # GIMS - Git Made Simple --> <img width="1658" height="609" alt="gims" src="https://github.com/user-attachments/assets/fd4ae515-9674-4cc2-8ea0-39d21e82e274" />

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

</div>

---

✨ Features

• 🤖 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

---

📦 Installation

npm install -g gims

Requirements: Node.js >= 18.18.0

---

⚡ Quick Start

# 1. 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

# 2. Start using it!
g s                         # Check status with AI insights
g o                         # AI commit + push (one command!)

Your New Workflow

# Before (traditional git)
git add .
git commit -m "trying to think of message..."
git push

# After (with GIMS)
g o                         # That's it. AI handles the rest.

---

📚 Commands

🧠 Core Commands

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

📊 Analytics & Review

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

⚡ Workflow Shortcuts

| 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) |

🛠️ Git Helpers

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

🔢 S4 Versioning (New)

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.

🔧 Setup & Config

| Command | Description | |---------|-------------| | g setup | Interactive setup wizard | | g setup --api-key <provider> | 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.

1. Model Context Protocol (MCP) Server

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:

{
  "mcpServers": {
    "gims": {
      "command": "node",
      "args": ["/path/to/gims/mcp/index.js"]
    }
  }
}

2. OpenAI / Custom Agent Integration

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

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 |

Setting Up API Keys

Option 1: Interactive Setup (Recommended)

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.):

# 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

Getting API Keys

<details> <summary><b>🔷 Gemini (Recommended)</b></summary>

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

</details> <details> <summary><b>🟢 Groq</b></summary>

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

</details> <details> <summary><b>🟡 OpenAI</b></summary>

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

</details>

---

🔧 Configuration

# View current settings
g config --list

# Enable conventional commits (feat:, fix:, etc.)
g config --set conventional=true

# Auto-stage all changes before commit
g config --set autoStage=true

# Disable clipboard copy
g config --set copy=false

# Show/hide progress indicators
g config --set progressIndicators=true

Configuration Options

| 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

Daily Workflow

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

Code Review Before Commit

g r              # Get AI review of your changes
g o              # Commit if review looks good

Handling Branch Issues

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

Working with Stashes

g ss             # Quick stash
g main           # Switch to main and pull
# ... check something ...
g pop            # Get your work back

Large Changeset

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

g --help         # Full command list with descriptions
g q              # Quick reference card
g <command> -h   # Help for specific command

---

🤝 Contributing

Contributions are welcome! Feel free to:

• 🐛 Report bugs
• 💡 Suggest features
• 🔧 Submit pull requests

---

📄 License

MIT © S41R4J

---

<div align="center">

⬆ Back to Top

Made with ❤️ for developers who'd rather code than write commit messages

</div>