Clipboard Synchronization
How Shen synchronizes text, images, and files across supported platforms.
Shen provides seamless, bidirectional clipboard synchronization between your host machine and remote streaming sessions. This ensures that text, images, and file references can be shared across environments as if they were running locally.
Architecture
The clipboard system is designed for high performance and reliability, with platform-specific implementations to handle OS-level sandboxing and multi-window environments.
Platform Implementations
- Windows & Linux: Uses the Electron
clipboardAPI directly within the main process. - macOS: Due to App Sandbox restrictions and the need for low-level
NSPasteboardaccess, Shen uses a dedicatedclipboard-helpersubprocess.
macOS Helper Watchdog
To prevent the accumulation of "orphan" processes, the macOS clipboard-helper includes a parent-process watchdog. It utilizes the kqueue kernel facility with NOTE_EXIT to monitor the main Shen process. If Shen terminates unexpectedly, the helper detects the parent's exit and shuts itself down immediately.
Multi-Window Orchestration
Shen supports multiple concurrent streaming windows, managed by a singleton clipboard controller:
- Singleton Helper: Only one instance of the clipboard-helper (on macOS) or the main process listener (Windows/Linux) is active, regardless of how many windows are open.
- Transparent IPC Relay: Clipboard events are fanned out from the main process to every active remote renderer.
- Deduplication & Routing: When the server pushes a clipboard update back to the host, Shen uses a
content_hashcheck. This ensures that the window which originated the copy does not attempt to "paste" the same data back into the host OS, preventing infinite feedback loops. - Late-Joiner Cache: If you copy a file or text locally and then open a streaming window, the new window will receive the most recent clipboard announcement immediately upon connection.
Performance Optimization
Clipboard payloads are transmitted via a dedicated binary channel. By avoiding Base64 encoding, Shen achieves:
- ~33% reduction in network payload size.
- Lower CPU overhead on both the host and the remote client.
- Faster transfer for large image or file-list data.
Host → Shen Push Behaviour
To prevent the clipboard from interrupting your workflow, Shen implements a 2-second suppression window. If you are actively typing or providing input in a streaming window, Shen will delay pushing host clipboard changes to that specific remote session for 2 seconds to avoid race conditions or unexpected focus steals.
Supported Content Types
| Type | Description |
|---|---|
| Plain Text | UTF-8 encoded text strings. |
| HTML | Rich text formatting (where supported by the remote app). |
| Images | PNG and JPEG formats are synchronized as bitmaps. |
| File References | Copying files in Explorer/Finder allows "pasting" the file path/data into the remote session. |
Troubleshooting
Privacy & Security (macOS)
On macOS, ensure Shen has the necessary permissions. If the clipboard is not syncing, check:
System Settings > Privacy & Security > Accessibility and ensure Shen is enabled.
Singleton Constraints
Shen ensures exactly one clipboard-helper is running. If you suspect a hang, check your Activity Monitor for clipboard-helper. The watchdog should handle this automatically, but a manual restart may be required in extreme cases.
General Fix
If synchronization stops working:
- Close all active streaming windows.
- Fully quit Shen (from the tray/menu bar).
- Restart Shen and reconnect.