Skip to main content
skill CX Codex

real-time-collaboration-engine — Claude Code skill: how to install

real-time-collaboration-engine guides real-time collaborative editing using WebSockets, OT, and CRDTs. Useful for building multi-user document editors, shared boards, and presence tracking.

MIT 195 installs ★ 274 updated 2026-10-30

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add curiositech/some_claude_skills --skill real-time-collaboration-engine -a claude-code
Open on GitHub

What real-time-collaboration-engine does

This skill provides architectural guidance for multi-user editing environments similar to Google Docs. It assists in choosing conflict resolution algorithms: Operational Transform for text sequences or CRDTs such as yjs and automerge for JSON objects. It also covers cursor tracking and presence awareness over WebSockets.

The instructions address frequent real-time pitfalls. Broadcasting every single keystroke floods networks with hundreds of messages per minute. The skill solves this by grouping edits into 200 ms batches. It also demonstrates client-side queuing to preserve edits during network drops and sync them upon reconnection.

The skill requires permissions to read and edit files, as well as run bash commands via npm. It explicitly avoids simple chat apps or read-only feeds, focusing instead on state synchronization.

What it helps with

  • Choose between Operational Transform (OT) and CRDTs for specific data structures
  • Batch text edits over WebSockets to reduce network congestion
  • Queue changes during disconnections to sync safely upon reconnecting
  • Prevent data loss from concurrent edits with OT or Yjs

Example prompts for the agent

  • Help me implement real-time text sync using OT and WebSockets without losing concurrent edits.
  • How do I set up CRDTs with Yjs for a shared whiteboard document?
  • Write an offline queue in TypeScript that batches and syncs pending changes on reconnect.

How to install real-time-collaboration-engine

1Skills CLI (Vercel)

npx skills add curiositech/some_claude_skills --skill real-time-collaboration-engine -a claude-code

2Manually: put the files in place

~/.claude/skills/real-time-collaboration-engine/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/real-time-collaboration-engine/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about real-time-collaboration-engine

How do I install real-time-collaboration-engine in Claude Code?

Run npx skills add curiositech/some_claude_skills --skill real-time-collaboration-engine -a claude-code. Alternatively, copy the file into ~/.claude/skills/real-time-collaboration-engine/SKILL.md.

What projects should use this skill?

Use it for multi-user editors, whiteboards, video timelines, and collaborative game state. It is not intended for basic chat apps or standard REST APIs.

When should I choose OT over CRDT?

Operational Transform fits ordered text sequences, while CRDTs like yjs or automerge work best for JSON structures and offline-first syncing.

Source text

SKILL.md · MIT
---
name: real-time-collaboration-engine
description: Build real-time collaborative editing with WebSockets, OT/CRDT conflict resolution, and presence awareness. Implements cursor tracking, optimistic updates, and offline sync. Use for collaborative
  editors, whiteboards, video editing. Activate on "real-time collaboration", "WebSocket sync", "multiplayer editing", "CRDT", "presence awareness". NOT for simple chat, request-response APIs, or single-user
  apps.
allowed-tools: Read,Write,Edit,Bash(npm:*,websocket:*)
metadata:
  category: DevOps & Site Reliability
  tags:
  - real
  - time
  - collaboration
  - real-time-collaboration
  - websocket-sync
  pairs-with:
  - skill: websocket-streaming
    reason: WebSocket transport is the foundation for real-time collaborative editing connections
  - skill: react-performance-optimizer
    reason: Optimistic updates and cursor rendering require React performance optimization
  - skill: security-auditor
    reason: Collaborative editing requires access control and input sanitization security auditing
---

# Real-Time Collaboration Engine

Expert in building Google Docs-style collaborative editing with WebSockets, conflict resolution, and presence awareness.

## When to Use

✅ **Use for**:
- Collaborative text/code editors
- Shared whiteboards and design tools
- Multi-user video editing timelines
- Real-time data dashboards
- Multiplayer game state sync

❌ **NOT for**:
- Simple chat applications (use basic WebSocket)
- Request-response APIs (use REST/GraphQL)
- Single-user applications
- Read-only data streaming (use Server-Sent Events)

## Quick Decision Tree

```
Need real-time collaboration?
├── Text editing? → Operational Transform (OT)
├── JSON data structures? → CRDTs
├── Cursor tracking only? → Simple WebSocket + presence
├── Offline-first? → CRDTs (better offline merge)
└── No conflicts possible? → Basic broadcast
```

---

## Technology Selection

### Conflict Resolution Strategies (2024)

| Strategy | Best For | Complexity | Offline Support |
|----------|----------|------------|-----------------|
| Operational Transform (OT) | Text, ordered sequences | High | Limited |
| CRDTs | JSON objects, sets | Medium | Excellent |
| Last-Write-Wins | Simple state | Low | Basic |
| Three-Way Merge | Git-style editing | High | Good |

**Timeline**:
- 2010: Google Wave uses OT
- 2014: Figma adopts CRDTs
- 2019: Yjs (CRDT library) released
- 2022: Automerge 2.0 (CRDT library) released
- 2024: PartyKit simplifies real-time infrastructure

---

## Common Anti-Patterns

### Anti-Pattern 1: Broadcasting Every Keystroke

**Novice thinking**: "Send every change immediately for real-time feel"

**Problem**: Network floods with tiny messages, poor performance.

**Wrong approach**:
```typescript
// ❌ Sends message on every keystroke
function Editor() {
  const handleChange = (text: string) => {
    socket.emit('text-change', { text });  // Every keystroke!
  };

  return <textarea onChange={(e) => handleChange(e.target.value)} />;
}
```

**Why wrong**: 100 WPM typing = 500 messages/minute = network congestion.

**Correct approach**:
```typescript
// ✅ Batches changes every 200ms
function Editor() {
  const [pendingChanges, setPendingChanges] = useState<Change[]>([]);

  useEffect(() => {
    const interval = setInterval(() => {
      if (pendingChanges.length > 0) {
        socket.emit('text-batch', { changes: pendingChanges });
        setPendingChanges([]);
      }
    }, 200);

    return () => clearInterval(interval);
  }, [pendingChanges]);

  const handleChange = (change: Change) => {
    setPendingChanges(prev => [...prev, change]);
  };

  return <textarea onChange={handleChange} />;
}
```

**Impact**: 500 messages/minute → 5 messages/second (90% reduction).

---

### Anti-Pattern 2: No Conflict Resolution Strategy

**Problem**: Concurrent edits cause data loss or corruption.

**Symptom**: Users see their changes disappear, documents become inconsistent.

**Wrong approach**:
```typescript
// ❌ Last write wins, overwrites concurrent changes
socket.on('text-change', ({ userId, text }) => {
  setDocument(text);  // Loses concurrent edits!
});
```

**Why wrong**: If User A and B edit simultaneously, one change is lost.

**Correct approach (OT)**:
```typescript
// ✅ Operational Transform for text
import { TextOperation } from 'ot.js';

socket.on('operation', ({ userId, operation, revision }) => {
  const transformed = transformOperation(
    operation,
    pendingOperations,
    revision
  );

  applyOperation(transformed);
  incrementRevision();
});

function transformOperation(
  incoming: Operation,
  pending: Operation[],
  baseRevision: number
): Operation {
  // Transform incoming against pending operations
  let transformed = incoming;
  for (const op of pending) {
    transformed = TextOperation.transform(transformed, op)[0];
  }
  return transformed;
}
```

**Correct approach (CRDT)**:
```typescript
// ✅ CRDT for JSON objects
import * as Y from 'yjs';

const ydoc = new Y.Doc();
const ytext = ydoc.getText('document');

// Automatically handles conflicts
ytext.insert(0, 'Hello');

// Sync with peers
const provider = new WebsocketProvider('ws://localhost:1234', 'room', ydoc);
```

**Impact**: Concurrent edits merge correctly, no data loss.

---

### Anti-Pattern 3: Not Handling Disconnections

**Problem**: User goes offline, loses work or sees stale state.

**Wrong approach**:
```typescript
// ❌ No offline handling
socket.on('disconnect', () => {
  console.log('Disconnected');  // That's it?!
});
```

**Why wrong**: Pending changes lost, no reconnection strategy, bad UX.

**Correct approach**:
```typescript
// ✅ Queue changes offline, sync on reconnect
const [isOnline, setIsOnline] = useState(true);
const [offlineQueue, setOfflineQueue] = useState<Change[]>([]);

socket.on('disconnect', () => {
  setIsOnline(false);
  showToast('Offline - changes will sync when reconnected');
});

socket.on('connect', () => {
  setIsOnline(true);

  // Send queued changes
  if (offlineQueue.length > 0) {
    socket.emit('sync-offline-changes', { changes: offlineQueue });
    setOfflineQueue([]);
  }
});

const handleChange = (change: Change) => {
  if (isOnline) {
    socket.emit('change', change);
  } else {
    setOfflineQueue(prev => [...prev, change]);
  }
};
```

**Timeline context**:
- 2015: Offline-first apps rare
- 2020: PWAs make offline UX standard
- 2024: Users expect seamless offline editing

---

### Anti-Pattern 4: Client-Only State Sync

**Problem**: No server authority, clients get out of sync.

**Wrong approach**:
```typescript
// ❌ Clients broadcast to each other directly
socket.on('peer-change', ({ userId, change }) => {
  applyChange(change);  // No validation, no server state
});
```

**Why wrong**: Malicious client can send invalid data, no recovery from desync.

**Correct approach**:
```typescript
// ✅ Server is source of truth
// Client
socket.emit('operation', { operation, clientRevision });

socket.on('ack', ({ serverRevision }) => {
  if (serverRevision !== expectedRevision) {
    // Desync detected, request full state
    socket.emit('request-full-state');
  }
});

// Server
io.on('connection', (socket) => {
  socket.on('operation', ({ operation, clientRevision }) => {
    // Validate operation
    if (!isValid(operation)) {
      socket.emit('error', { message: 'Invalid operation' });
      return;
    }

    // Apply to server state
    const serverRevision = applyOperation(operation);

    // Broadcast to all clients
    io.emit('operation', { operation, serverRevision });
  });
});
```

**Impact**: Data integrity guaranteed, can recover from client bugs.

---

### Anti-Pattern 5: No Presence Awareness

**Problem**: Users can't see who's editing what, causing edit conflicts.

**Symptom**: Two people editing same section unknowingly.

**Wrong approach**:
```typescript
// ❌ No awareness of other users
function Editor() {
  return <textarea />;  // Flying blind!
}
```

**Correct approach**:
```typescript
// ✅ Show active users and cursors
import { usePresence } from './usePresence';

function Editor() {
  const { users, updateCursor } = usePresence();

  const handleCursorMove = (position: number) => {
    socket.emit('cursor-move', { userId: myId, position });
  };

  return (
    <div>
      {/* Show who's online */}
      <UserList users={users} />

      {/* Show remote cursors */}
      <EditorWithCursors
        content={content}
        cursors={users.map(u => u.cursor)}
        onCursorMove={handleCursorMove}
      />
    </div>
  );
}
```

**Features**:
- Active user list with avatars
- Cursor positions color-coded by user
- Selection ranges highlighted
- "User X is typing..." indicators

---

## Implementation Patterns

### Pattern 1: WebSocket Setup with Reconnection

```typescript
import { io } from 'socket.io-client';

const socket = io('ws://localhost:3000', {
  reconnection: true,
  reconnectionDelay: 1000,
  reconnectionDelayMax: 5000,
  reconnectionAttempts: Infinity,
  transports: ['websocket', 'polling']  // Fallback
});

socket.on('connect', () => {
  console.log('Connected:', socket.id);
});

socket.on('disconnect', (reason) => {
  if (reason === 'io server disconnect') {
    // Server disconnected, manually reconnect
    socket.connect();
  }
});

socket.on('connect_error', (error) => {
  console.error('Connection error:', error);
});
```

### Pattern 2: Operational Transform (Text)

```typescript
import { TextOperation } from 'ot.js';

class OTEditor {
  private revision = 0;
  private pendingOperations: TextOperation[] = [];

  applyLocalOperation(op: TextOperation): void {
    // Apply immediately (optimistic update)
    this.applyToEditor(op);

    // Send to server
    this.sendOperation(op);

    // Store as pending
    this.pendingOperations.push(op);
  }

  receiveRemoteOperation(op: TextOperation, serverRevision: number): void {
    // Transform against pending operations
    let transformed = op;
    for (const pending of this.pendingOperations) {
      [transformed, pending] = TextOperation.transform(transformed, pending);
    }

    // Apply transformed operation
    this.applyToEditor(transformed);
    this.revision = serverRevision;
  }

  acknowledgeOperation(serverRevision: number): void {
    // Remove acknowledged operation from pending
    this.pendingOperations.shift();
    this.revision = serverRevision;
  }
}
```

### Pattern 3: CRDT with Yjs

```typescript
import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';

// Create shared document
const ydoc = new Y.Doc();

// Define shared types
const ytext = ydoc.getText('content');
const ymap = ydoc.getMap('metadata');
const yarray = ydoc.getArray('users');

// Connect to sync server
const provider = new WebsocketProvider(
  'ws://localhost:1234',
  'room-name',
  ydoc
);

// Listen to changes
ytext.observe(event => {
  console.log('Text changed:', event.changes);
});

// Make changes (automatically synced)
ytext.insert(0, 'Hello ');
ytext.insert(6, 'World!');

// Undo/redo support
const undoManager = new Y.UndoManager(ytext);
undoManager.undo();
undoManager.redo();
```

### Pattern 4: Presence Awareness

```typescript
import { Awareness } from 'y-protocols/awareness';

const awareness = provider.awareness;

// Set local state
awareness.setLocalState({
  user: {
    name: 'Alice',
    color: '#ff0000',
    cursor: { line: 10, ch: 5 }
  }
});

// Listen to changes
awareness.on('change', ({ added, updated, removed }) => {
  // Update UI with user cursors/selections
  const states = awareness.getStates();
  states.forEach((state, clientId) => {
    if (clientId !== awareness.clientID) {
      renderCursor(state.user.cursor, state.user.color);
    }
  });
});
```

### Pattern 5: Optimistic Updates with Rollback

```typescript
class OptimisticEditor {
  private optimisticChanges = new Map<string, Change>();

  async applyChange(change: Change): Promise<void> {
    const changeId = generateId();

    // Apply immediately (optimistic)
    this.applyToUI(change);
    this.optimisticChanges.set(changeId, change);

    try {
      // Send to server
      const result = await this.sendToServer(change);

      // Success - remove from optimistic
      this.optimisticChanges.delete(changeId);

    } catch (error) {
      // Failed - rollback
      this.rollback(changeId);
      this.showError('Could not apply change');
    }
  }

  private rollback(changeId: string): void {
    const change = this.optimisticChanges.get(changeId);
    if (change) {
      this.revertInUI(change);
      this.optimisticChanges.delete(changeId);
    }
  }
}
```

---

## Production Checklist

```
□ WebSocket connection with auto-reconnect
□ Offline queue for pending changes
□ Conflict resolution strategy (OT or CRDT)
□ Server authority (clients can't desync)
□ Presence awareness (cursors, active users)
□ Optimistic updates with rollback
□ Change batching (not per-keystroke)
□ Message compression for large payloads
□ Authentication and authorization
□ Rate limiting (prevent spam)
□ Heartbeat/ping-pong to detect dead connections
□ Graceful degradation (falls back to polling if WebSocket fails)
```

---

## When to Use vs Avoid

| Scenario | Strategy |
|----------|----------|
| Text editing (Google Docs) | ✅ Operational Transform |
| JSON objects (Figma) | ✅ CRDTs (Yjs, Automerge) |
| Simple cursor sharing | ✅ Basic WebSocket + presence |
| Chat messages | ✅ Simple append-only (no OT/CRDT) |
| Video timeline editing | ✅ CRDTs for timeline, OT for text |
| Read-only dashboards | ❌ Use Server-Sent Events instead |

---

## References

- `/references/ot-vs-crdt.md` - Deep comparison of conflict resolution strategies
- `/references/websocket-scaling.md` - Scaling to millions of concurrent connections
- `/references/presence-patterns.md` - Cursor tracking, user awareness, activity indicators

## Scripts

- `scripts/collaboration_tester.ts` - Simulate concurrent edits, test conflict resolution
- `scripts/latency_simulator.ts` - Test behavior under high latency/packet loss

---

**This skill guides**: Real-time collaboration | WebSocket architecture | Operational Transform | CRDTs | Presence awareness | Conflict resolution

© curiositech · MIT · curiositech/some_claude_skills

Similar skills

All skills for Frontend and UI →

From the same set180

The whole set →
skill-logger skill-logger — a skill for Claude Code, Codex, Cursor and more: records every skill invocation, computes a quality score, and captures feedback signals. Activate it when you want to know which skills underperform and why. CX Codex +1 197installs site-reliability-engineer The site-reliability-engineer skill checks Docusaurus builds for MDX issues, validates links, and helps catch site problems before deployment. CX Codex +1 196installs skill-documentarian skill-documentarian keeps a Claude Skills site in sync with its source files, metadata, tags, and badges. Use it when adding or checking skills. CX Codex +1 196installs vr-avatar-engineer vr-avatar-engineer guides work on VR avatar systems with facial tracking, network sync, and skin rendering. Useful for projects targeting Vision Pro, Quest, or PC VR. CX Codex +1 195installs competitive-cartographer competitive-cartographer maps competitive spaces and identifies white space opportunities for products, services, or personal brands. Helps define clear differentiation in crowded markets. CX Codex +1 194installs vibe-matcher vibe-matcher translates abstract brand feelings and adjectives into concrete design parameters like color palettes, typefaces, layouts, and interaction speeds. CX Codex +1 194installs hrv-alexithymia-expert hrv-alexithymia-expert is a Claude Code skill that adds expertise in heart rate variability metrics and alexithymia, connecting biometric data with emotional states. CX Codex +1 193installs frontend-architect frontend-architect — a skill for choosing a frontend framework, deploying to Cloudflare Pages, and building internal tool architectures. Recommends tech stacks, configures shadcn/ui, and bridges design tokens to components. CX Codex +1 191installs

Project sponsors

Companies that keep this analytics open