PBSync

A Ruby gem for bidirectional clipboard synchronization between machines over SSH using Unix domain sockets.

Features

Bidirectional sync: Changes on either machine are automatically synchronized
SSH tunneling: Secure connection between machines
Cross-platform: Works on macOS, Linux, and Windows (via clipboard gem)
Simple setup: No configuration files needed
Automatic deduplication: Prevents sync loops and duplicate transfers
UTF-8 support: Handles international text and emoji correctly
Size limits: Protects against oversized clipboard content (1MB max)

Installation

From RubyGems (when published)

gem install pbsync

From Source

git clone https://github.com/yourusername/pbsync.git
cd pbsync
bundle install
gem build pbsync.gemspec
gem install ./pbsync-0.1.0.gem

Usage

Basic Usage

Simply connect to a remote machine:

pbsync connect hostname

That's it! Your clipboards are now synchronized. Copy text on either machine and it will appear on the other.

The connect command automatically:

Establishes an SSH connection to the remote host
Starts the pbsync server on the remote machine
Creates a secure tunnel for clipboard synchronization
Begins monitoring both clipboards for changes

Verbose Mode

For debugging or to see detailed operation logs:

pbsync connect hostname --verbose
# or
pbsync connect hostname -v

Command Reference

# Show help
pbsync --help

# Connect to remote server (most common usage)
pbsync connect <hostname> [--verbose]

# Manually start server mode (rarely needed)
pbsync serve [--verbose]

# Show subcommand help
pbsync connect --help
pbsync serve --help

Manual Server Mode

The serve command is available if you need to manually start a server, but this is rarely necessary since connect handles it automatically. You might use it for:

Testing the server locally
Running pbsync in a non-SSH environment
Custom networking setups

How It Works

Server Mode: Creates a Unix domain socket at /tmp/pbsync.sock and waits for connections
Client Mode: Establishes an SSH tunnel to the remote host, forwarding the Unix socket
Monitoring: Both sides poll their clipboard every 0.5 seconds for changes
Synchronization: When a change is detected, it's sent to the other side via the socket
Deduplication: Tracks sent and received content to prevent echo loops

Protocol

PBSync uses a simple binary protocol:

4-byte length prefix (network byte order)
UTF-8 encoded clipboard content
Maximum message size: 1MB

Requirements

Ruby 2.7 or higher
SSH access to the remote machine
pbsync installed on both machines
The remote machine must have pbsync in its $PATH

Development

Setup

# Clone the repository
git clone https://github.com/yourusername/pbsync.git
cd pbsync

# Install dependencies
bundle install

Testing

# Run all tests
bundle exec rake spec

# Run with coverage report
bundle exec rake coverage

# Run specific test suites
bundle exec rake unit        # Unit tests only
bundle exec rake integration # Integration tests only

Code Quality

# Run RuboCop linter
bundle exec rake lint

# Auto-fix linting issues
bundle exec rake lint_fix

Building

# Build the gem
gem build pbsync.gemspec

# Install locally for testing
gem install ./pbsync-0.1.0.gem

Architecture

┌─────────────┐                    ┌─────────────┐
│  Local      │                    │  Remote     │
│  Machine    │                    │  Machine    │
├─────────────┤                    ├─────────────┤
│  Clipboard  │◄──┐            ┌──►│  Clipboard  │
└─────────────┘   │            │   └─────────────┘
       ▲          │            │          ▲
       │          │            │          │
       ▼          │            │          ▼
┌─────────────┐   │            │   ┌─────────────┐
│  PBSync     │   │            │   │  PBSync     │
│  Client     │   │            │   │  Server     │
├─────────────┤   │            │   ├─────────────┤
│ Monitor &   │   │            │   │ Monitor &   │
│ Send/Recv   │   │            │   │ Send/Recv   │
└─────────────┘   │            │   └─────────────┘
       ▲          │            │          ▲
       │          ▼            ▼          │
       └──────────────────────────────────┘
              SSH Tunnel + Unix Socket

Troubleshooting

Connection Issues

If you can't connect:

Ensure pbsync is installed on both machines
Verify SSH access: ssh hostname
Check that pbsync is in the remote machine's $PATH
Use verbose mode (-v) to see detailed logs

Clipboard Not Syncing

Check that the clipboard contains text (not images or files)
Verify the content is under 1MB
Try verbose mode to see what's being sent/received
Ensure no other clipboard managers are interfering

Performance

The default polling interval is 0.5 seconds
Large clipboard content (near 1MB) may take longer to sync
Network latency affects synchronization speed

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Write tests for your changes
Ensure all tests pass (bundle exec rake spec)
Check code quality (bundle exec rake lint)
Commit your changes
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.