Git Sync Guardian

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)

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:

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

Manual

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:

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