---

✨ 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

``bash
npm install -g gims
`

Requirements: Node.js >= 18.18.0

---

⚡ Quick Start

`bash


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

$3

`bash


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

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

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

---

🤝 Contributing

Contributions are welcome! Feel free to:

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

---

📄 License

MIT © S41R4J

---