# Git Sync Guardian

MCP Server that watches `main` for new commits and keeps your working branch in sync — powered by local AI (Ollama).

## What it does

When you're working on a feature branch, `main` keeps moving. Git Sync Guardian:

1. **Monitors** `origin/main` at regular intervals
2. **Analyzes** incoming changes with Ollama (local LLM) to assess conflict risk
3. **Notifies** you via macOS native dialogs with risk level and recommended strategy
4. **Syncs** your branch (rebase or merge) with automatic stash/unstash
5. **Handles conflicts** — offers manual resolution, AI-assisted (Claude Code), or abort

## Requirements

- **Node.js** >= 18
- **Claude Code** (MCP host)
- **Ollama** running locally (optional — falls back to heuristics if unavailable)
- **macOS** (notifications use `osascript`)

## Installation

### Automatic (recommended)

```bash
curl -fsSL https://raw.githubusercontent.com/Mamisedra/git-sync-guardian/main/install.sh | bash
```

This will clone to `~/.git-sync-guardian`, build, and register the MCP server in Claude Code automatically.

To install in a custom directory:

```bash
curl -fsSL https://raw.githubusercontent.com/Mamisedra/git-sync-guardian/main/install.sh | bash -s -- /path/to/install
```

### Manual

```bash
git clone https://github.com/Mamisedra/git-sync-guardian.git
cd git-sync-guardian
npm install
npm run build
```

Then add to your `~/.claude.json`:

```json
{
  "mcpServers": {
    "git-sync-guardian": {
      "command": "node",
      "args": ["/absolute/path/to/git-sync-guardian/dist/index.js"]
    }
  }
}
```

Restart Claude Code to load the server.

## Usage

Git Sync Guardian exposes 4 tools in Claude Code:

### `init-sync` — Start monitoring

```
> Use init-sync on /path/to/my-repo
```

| Parameter | Default | Description |
|-----------|---------|-------------|
| `repoPath` | required | Absolute path to the git repo |
| `baseBranch` | `main` | Branch to watch |
| `remoteName` | `origin` | Git remote name |
| `intervalMinutes` | `30` | Check interval in minutes |

**Note:** You must be on a feature branch (not `main`) to start monitoring.

### `status` — Check current state

```
> Check git-sync-guardian status
```

Shows: monitoring state, divergence info, last analysis (strategy, risk level, conflict probability).

### `sync-now` — Immediate sync

```
> Run sync-now
```

| Parameter | Default | Description |
|-----------|---------|-------------|
| `strategy` | `auto` | `rebase`, `merge`, or `auto` (uses AI recommendation) |

Performs: fetch → stash → rebase/merge → unstash. Detects conflicts and offers resolution options.

### `stop-sync` — Stop monitoring

```
> Stop git-sync-guardian
```

## How the AI analysis works

When divergence is detected, the diff is sent to a local Ollama model which returns:

- **Strategy**: `rebase` (clean history) or `merge` (safer for conflicts)
- **Risk level**: `low` / `medium` / `high`
- **Conflict likelihood**: 0–100%
- **Reasoning**: Short explanation

If Ollama is unavailable, a heuristic fallback kicks in:
- No common files modified → rebase, low risk
- Common files modified → risk assessment based on overlap
- Many commits behind (>20) → merge preferred

## Configuration

Environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `GSG_OLLAMA_URL` | `http://localhost:11434` | Ollama API endpoint |
| `GSG_OLLAMA_MODEL` | `qwen2.5vl` | Ollama model for analysis |
| `GSG_LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |

## Architecture

```
src/
  index.ts              # MCP server entry point
  server.ts             # Tool registration (4 tools)
  core/
    sync-monitor.ts     # Main monitoring loop & sync orchestration
    git-operations.ts   # Git commands (fetch, rebase, merge, stash)
    diff-analyzer.ts    # Ollama AI analysis + heuristic fallback
    notifier.ts         # macOS native notifications (osascript)
  types/
    index.ts            # TypeScript interfaces & enums
  utils/
    config.ts           # Default configuration
    logger.ts           # Structured stderr logger
```

## License

MIT