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