Live Cursor for Obsidian

Live Cursor is an ultra-lightweight, zero-conflict real-time collaborative editing and configuration sync engine for Obsidian vaults. It brings real-time collaborative editing, live collaborator cursor tracking, and total vault synchronization across devices without complex setups.

---

Architecture & Connection Modes

Live Cursor is built with Simplicity in mind. We know setting up sync servers can be painful, so we’ve abstracted the technology into three seamless Connection Modes. Whether you are working across the room, across a corporate VPN, or from your mobile phone on a train, Live Cursor just works.

1. Host Local (LAN/Tailscale)

Best for: Desktop users who want a quick, private sync session with other computers on their Wi-Fi or VPN.

• How it works: When you click "Start Local Host" on a Desktop PC, Live Cursor silently spins up a lightweight Node.js background websocket daemon. It automatically scans your network interfaces and gives you ready-to-use IP addresses (e.g., ws://192.168.x.x:1234/sync).
• Simplicity: No terminals, no Docker, no configuration files. One click and your PC is the server.
• Limitations: Only works on Desktop OS (Windows, Mac, Linux). Mobile devices (iOS/Android) cannot act as the "Host" in this mode because mobile operating systems block background TCP port binding. Mobile devices can easily join this host, but they cannot be the host.

2. WebRTC P2P (Mobile Friendly)

Best for: Mobile users, serverless setups, and true Peer-to-Peer synchronization.

• How it works: This mode uses a decentralized WebRTC mesh network powered by y-webrtc. Instead of a central server, devices connect directly to each other using a shared "Room Name" and "Password".
• Serverless Vault Config Sync: Usually, syncing your .obsidian configuration files (themes, plugins) requires an HTTP server. Live Cursor elegantly bypasses this limitation on Mobile by pushing your configuration files directly over WebRTC Data Channels using a shared Y.Map. This means your mobile phone can fully act as a "Server" for configurations and real-time editing without needing a Node.js daemon.
• Simplicity: Enter a Room Name, and you are instantly syncing. No IPs, no port forwarding.
• Limitations: Requires an active internet connection to briefly hit public WebRTC signaling servers (which only facilitate the initial peer handshake, not the data itself).

3. Cloud Server

Best for: Enterprise teams, 24/7 always-on sync environments, and heavy multi-user collaboration.

• How it works: You deploy the background daemon (via Docker or Node) on a dedicated cloud VPS (like DigitalOcean, AWS, or a Raspberry Pi). You then point your Live Cursor settings to that ws:// URL.
• Simplicity: The plugin natively generates standard Docker Compose templates for you under the "Advanced Developer Settings" if you want to self-host.
• Limitations: Requires technical knowledge to deploy a cloud server, setup DNS, and manage SSL/TLS if you want secure web-socket (wss://) traffic.

---

Features

• Real-Time Cursor Tracking: View the live cursors and text selections of other vault editors inside your notes with custom user profiles and dynamic hex colors.
• Config Sync Engine: One-click bidirectional synchronization of settings, themes, and community plugins (your .obsidian configuration folder). Handles file conflicts gracefully by moving conflicted copies into a designated Sync Conflicts/ folder while preserving directory structures.
• Admin Diagnostics: Secure telemetry dashboard reporting uptime, connected rooms, memory utilization, and local SQLite/event-log database sizes (available on dedicated cloud instances).
• Zero-Conflict JSON Merge: Automatically attempts to deep-merge standard plugin configurations before falling back to manual review.

---

Submitting to the Obsidian Community Plugins Tab

To make this plugin downloadable directly from the official Community Plugins catalog inside Obsidian, follow these steps:

1. Build and Release

Compile the plugin code locally:

npm run build

This updates main.js and compiles the background daemon launcher.

Create a new Release in your GitHub repository (Live-Cursor/Live-Cursor):

• Name the release exactly matching your version in manifest.json (e.g. 1.0.0).
• Attach the following three compiled files as assets to the GitHub Release:
  1. main.js
  2. manifest.json
  3. styles.css

2. Submit to Obsidian Releases

1. Fork the official obsidianmd/obsidian-releases repository on GitHub.
2. Edit community-plugins.json inside your fork and append your plugin configuration object at the end:

   {
     "id": "live-cursor",
     "name": "Live Cursor",
     "author": "Live-Cursor Organization",
     "description": "Real-time collaborative editing and cursor tracking for Obsidian notes.",
     "repo": "Live-Cursor/Live-Cursor"
   }
   

3. Commit the change and submit a Pull Request to the obsidian-releases repository. The Obsidian development team will automatically review, verify compliance, and add it to the live catalog!

---

License

This project is licensed under the MIT License.