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

---

✨ 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

🔷 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

# 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

---

⬆ Back to Top

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