Maintaining forked repositories is tedious. Upstream authors keep shipping changes, and every sync risks merge conflicts. You either:
- ❌ Forget to sync — your fork falls behind, missing bug fixes and features
- ❌ Resolve conflicts manually — reading
<<<<<<<markers for hours - ❌ Give up and re-fork — losing your local modifications
ForkSync solves this. It automatically syncs your forks and uses AI coding agents (Claude Code, OpenCode, Droid, Codex) to resolve merge conflicts — so you never have to touch conflict markers again.
| Feature | Description |
|---|---|
| 🔄 Auto Sync | Periodically fetches and merges upstream changes (configurable interval) |
| 🤖 AI Conflict Resolution | Delegates merge conflicts to AI agents (Claude Code, OpenCode, Droid, Codex) |
| 🖥️ Desktop App | Polished Electron GUI — dashboard, conflict viewer, settings |
| ⌨️ CLI | Full-featured command-line tool for terminal workflows |
| 🔍 Directory Scanner | Recursively scans any directory to discover and batch-add fork repos |
| 📝 Sync History | SQLite-backed history with filters, AI-generated summaries, and cleanup |
| 🔔 System Notifications | macOS native alerts on sync success, conflicts, or errors |
| 🖥️ IDE Integration | Open repos directly in VSCode, Cursor, or Trae |
| 🌐 i18n | Multi-language interface |
| ⚙️ Flexible Strategies | preserve_ours / preserve_theirs / balanced / agent_resolve |
Grab the latest release for your platform:
| Platform | Format | Link |
|---|---|---|
| macOS | .dmg |
Releases |
| Linux | .AppImage |
Releases |
| Windows | .exe (NSIS) |
Releases |
git clone https://github.com/loongxjin/forksync.git
cd forksync
# Full build (Go engine + Electron app)
make build
# Output: app/dist/cd engine && go build -o forksync . && ./forksync --helpmkdir -p ~/.forksyncEdit ~/.forksync/config.yaml:
github:
token: "ghp_your_token_here"Token is optional but recommended — it enables automatic upstream detection via GitHub API.
# Add a single repo
forksync add ~/projects/my-fork
# Scan a directory to batch-discover fork repos
forksync scan ~/projects# Sync all repos
forksync sync --all
# Sync a specific repo
forksync sync my-fork
# Start background sync service (every 30 min)
forksync serve# Resolve conflicts using AI (interactive)
forksync resolve my-fork
# Use a specific agent, auto-commit
forksync resolve my-fork --agent claude --no-confirmcd app && npm install && npm run devThis is the core feature that sets ForkSync apart. When a sync produces merge conflicts, ForkSync can automatically delegate resolution to an AI coding agent:
┌─────────────┐ conflict ┌───────────────┐ resolve ┌────────────────┐
│ Upstream │ ──────────────▶ │ ForkSync │ ────────────▶│ AI Agent │
│ Change │ │ detects │ │ (Claude/etc.) │
└─────────────┘ │ conflict │ └───────┬────────┘
└───────────────┘ │
│ resolved
▼
┌───────────────┐ ┌────────────────┐
│ ForkSync │ ◀───────────│ Verify & │
│ commits │ commit │ Commit │
└───────────────┘ └────────────────┘
Supported Agents:
| Agent | Binary | Auto-detected |
|---|---|---|
| Claude Code | claude |
✅ |
| OpenCode | opencode |
✅ |
| Droid | droid |
✅ |
| Codex | codex |
✅ |
Agents are auto-discovered via PATH. Set a preferred agent in config:
agent:
preferred: "claude"
conflict_strategy: "agent_resolve"Resolution strategies:
| Strategy | Behavior |
|---|---|
preserve_ours |
Keep local changes, accept non-conflicting upstream |
preserve_theirs |
Prefer upstream changes |
balanced |
Smart merge preserving both sides |
agent_resolve |
Delegate to AI agent |
Built with Electron + React + TypeScript + Tailwind CSS + shadcn/ui.
| Page | Description |
|---|---|
| Dashboard | Overview: synced/conflict counts, recent activity, agent status |
| Repos | Add, scan, sync, remove repositories |
| Conflicts | List repos with conflicts, resolve via agents |
| Conflict Detail | Diff viewer, agent summary, accept/reject resolution |
| History | Sync timeline with filters and cleanup |
| Settings | General settings, agent config, IDE preferences, theme |
Architecture:
┌───────────────────────────────────┐
│ Electron UI (React) │
│ Dashboard · Repos · Conflicts │
│ History · Settings · Detail │
└───────────────┬───────────────────┘
│ IPC (contextBridge)
┌───────────────▼───────────────────┐
│ EngineClient (TypeScript) │
│ Spawns Go binary, parses JSON │
└───────────────┬───────────────────┘
│ --json flag
┌───────────────▼───────────────────┐
│ Go CLI Engine (Cobra) │
│ add · sync · resolve · serve │
│ agent · config · history │
└───────────────────────────────────┘
All commands support --json for structured output.
# Repository management
forksync add <path> [--upstream <url>] # Add repo
forksync remove <name> # Remove from tracking
forksync scan <directory> # Batch-discover fork repos
# Sync
forksync sync [--all | <name>] # Sync repos
forksync serve [--interval 15m] # Background sync service
forksync status # Show all repo statuses
# AI conflict resolution
forksync resolve <name> [--agent claude] [--no-confirm] [--accept] [--reject]
# Agent management
forksync agent list # Detect installed agents
forksync agent sessions # List active sessions
forksync agent cleanup # Remove expired sessions
# Configuration
forksync config get # Show all config
forksync config set <key> <value> # Set config value
forksync config keys # List available keys
# History
forksync history [--limit 20] [--cleanup [--keep-days 30]]Location: ~/.forksync/config.yaml
sync:
default_interval: "30m"
sync_on_startup: true
agent:
preferred: "claude"
priority: [claude, opencode, droid, codex]
timeout: "10m"
conflict_strategy: "agent_resolve"
confirm_before_commit: true
session_ttl: "24h"
github:
token: ""
notification:
enabled: true
proxy:
enabled: false
url: ""Data files:
| Path | Purpose |
|---|---|
~/.forksync/config.yaml |
User configuration |
~/.forksync/repos.json |
Managed repository list |
~/.forksync/sessions/<id>.json |
Agent session records |
~/.forksync/db/forksync.db |
SQLite sync history |
~/.forksync/logs/sync-*.log |
Daily-rotated log files |
forksync/
├── engine/ # Go CLI engine
│ ├── cmd/ # Cobra commands
│ ├── internal/
│ │ ├── agent/ # AI agent adapters (Claude, OpenCode, Droid, Codex)
│ │ │ └── session/ # Session lifecycle management
│ │ ├── config/ # Viper-based YAML config
│ │ ├── conflict/ # Merge conflict detection
│ │ ├── git/ # Git operations (go-git + CLI fallback)
│ │ ├── github/ # GitHub REST API client
│ │ ├── history/ # SQLite sync history store
│ │ ├── logger/ # File logger with daily rotation
│ │ ├── notify/ # macOS system notifications
│ │ ├── repo/ # Repository JSON store (thread-safe)
│ │ ├── scheduler/ # Background sync scheduler
│ │ └── sync/ # Core sync pipeline
│ └── pkg/types/ # Shared types
│
├── app/ # Electron desktop app
│ ├── src/main/ # Electron main process + EngineClient
│ ├── src/preload/ # Context bridge (window.api)
│ └── src/renderer/ # React UI (pages, components, contexts)
│
├── build/ # Build scripts
└── docs/ # Documentation
cd engine && go test ./... -v146 tests across 15 test files — covering sync pipeline, agent adapters, session management, git operations, conflict detection, config, history, and more.
See Development Guide for setup instructions and architecture details.