gims/README.md

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

[![npm version](https://img.shields.io/npm/v/gims.svg)](https://npmjs.org/package/gims)
[![npm downloads](https://img.shields.io/npm/dm/gims.svg)](https://npmjs.org/package/gims)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![AI Powered](https://img.shields.io/badge/AI-Powered-blueviolet.svg)](https://github.com/s41r4j/gims)
[![Node.js](https://img.shields.io/badge/Node.js->=18.18.0-green.svg)](https://nodejs.org)

**AI-powered Git CLI that writes your commit messages for you**

*Because life's too short for "fix stuff" commits* 🎯

[Installation](#-installation) • [Quick Start](#-quick-start) • [Commands](#-commands) • [AI Setup](#-ai-providers) • [Configuration](#-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

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

### Your New Workflow

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

### 🧠 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](https://github.com/s41r4j/s4vs)**, 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](https://modelcontextprotocol.io/) 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"]
    }
  }
}
```

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

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

### Setting Up API Keys

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

### Getting API Keys

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

1. Visit [Google AI Studio](https://aistudio.google.com/app/apikey)
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](https://console.groq.com/keys)
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](https://platform.openai.com/api-keys)
2. Create a new API key
3. Set it: `export OPENAI_API_KEY="your-key"` or run `g setup --api-key openai`

</details>

---

## 🔧 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
```

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

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

### Code Review Before Commit

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

### Handling Branch Issues

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

### Working with Stashes

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

### Large Changeset

```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 <command> -h   # Help for specific command
```

---

## 🤝 Contributing

Contributions are welcome! Feel free to:

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

---

## 📄 License

MIT © [S41R4J](https://github.com/s41r4j)

---

<div align="center">

**[⬆ Back to Top](#-gims---git-made-simple)**

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

</div>