Skip to content

crdt-sync-plugin

CRDT Sync Plugin

Status: Completed (core functionality)

Overview

Obsidian plugin providing conflict-free sync using CRDT (Yjs). Supports three modes:

File-only: Sync via SMB/Dropbox/cloud storage
Hybrid: Server when available, file fallback
Server-only: Real-time WebSocket sync

Location

obsidian-plugin/

Key Files

File	Purpose
`src/main.ts`	Plugin entry, settings, file hooks
`src/crdt-state-manager.ts`	Read/write .crdt state files
`src/file-sync-manager.ts`	Debounced save handling
`src/presence-manager.ts`	Track who’s editing what
`src/identity.ts`	Client ID generation
`manifest.json`	Plugin metadata
`package.json`	Dependencies (Yjs, diff-match-patch)

Features

Implemented

Pending

diff-match-patch for efficient updates
Conflict visualization UI
Mobile support
Binary file handling

How It Works

File-Only Mode

User edits project.md
       ↓
Plugin updates Y.Doc
       ↓
Plugin saves .crdt/project.md.{clientId}.yjs
       ↓
SMB/Dropbox syncs to other clients
       ↓
Other client opens project.md
       ↓
Plugin merges all .yjs files
       ↓
project.md updated with merged content

Hybrid Mode

Same as file-only, plus:

Connect to WebSocket server
Real-time updates when server available
Fall back to file sync when disconnected

Configuration

interface CrdtSyncSettings {
  clientId: string;           // Auto-generated UUID
  displayName: string;        // User's name
  syncMode: 'file-only' | 'hybrid' | 'server-only';
  serverUrl: string;          // ws://host:port
  backgroundCheckInterval: number;  // ms (default 3000)
  debounceDelay: number;      // ms (default 500)
  crdtFolderName: string;     // default '.crdt'
  showPresence: boolean;
  showPresenceNudge: boolean;
  showSyncStatus: boolean;
  showConflictNotifications: boolean;
}