ClipBridge

English · 简体中文

Local-first device transfer and GitHub-backed Agent handoff.

Current release: 0.7.12 · Agent Handoff Beta

ClipBridge 0.7 combines two focused workflows:

• Local relay: transfer text and files between Windows, Mac, iPhone, Android, and other devices on the same trusted private network. A Windows PC or Mac can be the relay node; browsers are management and endpoint devices.
• Agent Handoff Beta: move unfinished Git work and the context needed to continue it between computers through the user's existing GitHub repository. This workflow is computer-only because creating and applying handoffs requires Git and Node.js.

Agent Handoff in 0.7

Agent Handoff is the current product direction. It carries committed Git history, tracked unfinished changes, a structured Markdown summary, and machine-readable state without trying to copy a vendor-specific chat session.

1. On the sending computer, choose an existing Git project or clone one from the signed-in GitHub account.
2. Confirm the Git, Node.js, project, and GitHub checks are green, then register this computer.
3. Copy the official prompt to the current coding Agent and paste its completed handoff response back into ClipBridge.
4. Choose one or more registered receiving computers and publish the handoff.
5. On a receiving computer, open the same repository, refresh incoming handoffs, inspect the package, and apply it to a clean working tree.

The Send handoff and Receive handoff roles are separate in the UI. Existing projects can be safely fast-forwarded from GitHub; dirty, divergent, detached, or unpushed work is never silently overwritten. See the Agent Handoff guide for the complete workflow and safety model.

The language control in the top-right corner switches the complete interface between Chinese and English. ClipBridge follows the browser language on first use and remembers the user's choice on that device.

Experimental online WebRTC transfer from 0.6

The ClipBridge project site introduces the current local-transfer and Agent Handoff workflows. Its public HTTPS WebRTC transfer tool remains available as an experimental feature, but development is paused after usability evaluation.

1. Open https://junfei-z.github.io/clipbridge/transfer.html on both devices.
2. On one device choose Create connection to get a temporary 6-digit room code and QR code.
3. On the other device choose Join connection and enter the room code, or scan the QR code.
4. When both pages show Directly connected, send text or files in either direction.

The public PWA has no account and no content database. A Cloudflare Durable Object relays only the temporary WebRTC offer and answer; each 6-digit room expires after five minutes and accepts two devices. Text and file contents continue to travel directly between browsers. Some restrictive networks may require a TURN relay; ClipBridge reports connection failure rather than uploading content to an untrusted fallback. See the online PWA guide.

Local relay features in 0.7

• Pair an iPhone, iPad, Mac, Android device, or another computer with a one-time 6-digit code or local QR code.
• Give every paired device an independent 256-bit access key.
• Store only SHA-256 key hashes on Windows, never the usable device keys.
• Run a lightweight native menu bar relay on macOS or a notification-area relay on Windows.
• Keep the management-device role separate from the relay node, even when both roles run on one computer.
• View paired device names and last-seen times from the relay node panel.
• Revoke one device without breaking access for the others.
• Send Unicode plain text to a Windows or Mac relay and retrieve the current relay-node clipboard.
• Use a focused clipboard manager on the relay node and direction-aware Send / Receive modes remotely.
• Reuse, copy, delete, or clear the latest 50 explicit ClipBridge transfers from a device-scoped history.
• Choose a named target such as Windows, iPhone, or Mac instead of always sending in one direction.
• Select several named targets and send the same text or file to all of them in one action.
• Queue up to 50 pending texts per paired device in an isolated Windows-hosted inbox.
• Send photos, videos, PDFs, SVGs, source code, archives, and other files to a named paired device.
• Stream file uploads directly to Windows disk with progress and cancellation instead of buffering a whole video in memory.
• Open safe previews for common images, videos, PDFs, and plain-text code; SVG and HTML are shown as inert text rather than executed.
• Download through short-lived, single-use links that never place the device access key in the URL.
• Automatically remove temporary files after 24 hours, when the target deletes them, or when either paired device is revoked.
• Store one shared Blob for a multi-recipient file and track each recipient as pending or downloaded independently.
• Keep the same high-resolution ClipBridge mascot in the tray, browser, and iPhone Home Screen.
• Continue opening v0.1 shared-token links during migration.

Security boundary

Local-relay pairing and authorization are device-specific in 0.7, but LAN transport is still ordinary HTTP and is not encrypted. Run ClipBridge only on a trusted private network. Do not expose port 39393 to the internet, use it on public Wi-Fi, or transfer passwords, verification codes, private keys, or sensitive work material.

Pairing codes expire after five minutes, work once, and rate-limit incorrect guesses. QR codes are generated locally; ClipBridge does not send pairing links or clipboard content to a QR service or other cloud service.

Requirements

• Windows 10 or later, or macOS 12 or later
• Node.js 20 or later
• The relay node and other devices connected to the same trusted Wi-Fi or private LAN

Start ClipBridge on Windows

After downloading a source archive, open PowerShell in the extracted folder and install the single QR-code dependency once:

npm install

ClipBridge can still start and pair by 6-digit code if this optional QR renderer is not installed, but the scannable QR image will be unavailable.

Double-click:

Start-ClipBridge-Tray.cmd

Administrator access is not required. The temporary command window closes, the local panel opens in the default browser, and ClipBridge remains available from the Windows notification area. Starting it again opens the existing panel instead of creating a duplicate service.

The tray menu can open the Windows panel, copy the device URL, or stop ClipBridge. For development and diagnostics, run:

npm start

Windows Firewall may ask whether Node.js can accept connections. Allow it only on private networks.

Start ClipBridge on macOS

Install dependencies once in Terminal, then double-click Start-ClipBridge-Mac.command:

npm install
./Start-ClipBridge-Mac.command

The launcher uses Apple Command Line Tools to build a small native Objective-C/AppKit menu bar app in dist/ClipBridge.app. Using clang rather than Swift also keeps the launcher working when a partial Apple tools update leaves the Swift compiler and SDK at different patch builds. Its menu can open the management panel, copy the LAN device URL, or quit the Mac relay. Clipboard access uses the built-in pbpaste and pbcopy tools, so Unicode text does not pass through a legacy code page.

See the macOS relay guide for role definitions, requirements, and the hardware-validation boundary.

Pair an iPhone or another device

1. Open ClipBridge on the Windows or Mac relay node.
2. Under Paired devices, choose Pair new device.
3. Scan the local QR code with the iPhone camera, or open the copied device URL and enter the 6-digit code.
4. Confirm the device name and type, then choose Secure pair.
5. The device keeps its own access key in local browser storage. The key is not placed in the URL.

From the relay node you can later review the device and choose Revoke. The revoked device immediately loses clipboard access while every other paired device continues working.

Send between iPhone, Mac, and Windows

1. Pair each device with the same Windows or Mac ClipBridge relay.
2. Open Send and choose one or more named target devices.
3. Sending to the relay node writes immediately to its Windows or Mac clipboard.
4. Sending to another paired device places the text in that device's private inbox on the relay node.
5. The target opens Receive, chooses Copy and accept, and the item leaves its inbox while remaining available in scoped history.

The relay node must be running and every device must be on the same trusted private network. The target browser does not have to remain open while a text is queued.

Send a file from Android to iPhone through Windows

1. Pair both the Android phone and iPhone with the same Windows ClipBridge service.
2. On Android, open ClipBridge and switch from Text to Files.
3. Choose the paired iPhone and any other intended recipients, select one or more files, and choose Send files.
4. The relay node stores one inert temporary Blob per file and creates an independent delivery record for every target; it does not open or execute the file.
5. On iPhone, open Files, then open, download, or delete the item from that device's private file inbox.

The default limits are 256 MB per file, 1 GB of temporary file storage, and 24-hour retention. They can be changed in .clipbridge/config.json. iOS requires an explicit tap to download or save a received file; a local HTTP web app cannot silently write into Photos or Files.

Add ClipBridge to the iPhone Home Screen

After pairing in Safari, tap Share, then Add to Home Screen. The saved app opens without a token in its URL and uses the same ClipBridge icon as Windows. Safari may require manual long-press copying because clipboard APIs are restricted on non-HTTPS local pages.

If startup fails

ClipBridge shows an error dialog instead of leaving an empty command window. Diagnostic details are written to .clipbridge/server-error.log. You can also run npm start in PowerShell to see the service output directly.

Stored data

ClipBridge keeps local settings beside the relay in .clipbridge/:

• config.json contains the port, stable relay-node identity/platform, and the legacy v0.1 migration token.
• devices.json contains device metadata and key hashes. Usable per-device keys are never written there.
• history.json contains up to 50 text transfers explicitly made through ClipBridge, including source, target, and timestamp.
• inbox.json contains up to 50 pending texts per target device until that device accepts, ignores, or clears them.
• files.json contains shared Blob metadata and separate per-target delivery states, including source, target, size, checksum, and expiry time.
• files/ contains opaque temporary file blobs. Original filenames are never used as disk paths.

ClipBridge does not watch or index every relay clipboard change. History stays on the Windows or Mac relay node: its local management panel can see all entries, while a paired device only receives entries in which that device is the source or target. Single entries and the visible history scope can be cleared from either interface.

Apple Shortcuts migration

The paired web app is the recommended iPhone experience in 0.7. Existing v0.1 Apple Shortcuts continue to work with the legacy token while users migrate, but named targets and inboxes require secure device pairing. See docs/iphone-shortcuts.md for the compatibility setup and its security trade-off.

API

Paired remote requests use the device key returned by POST /api/v1/pair:

Authorization: Bearer <device-key>

Pair a device

POST /api/v1/pair
Content-Type: application/json

{"code":"123456","name":"Junfei's iPhone","type":"iphone"}

Pairing-session creation, device listing, and revocation are restricted to Windows loopback requests.

Read the Windows clipboard

GET /api/v1/clip

Write the Windows clipboard

POST /api/v1/clip
Content-Type: application/json

{"kind":"text","text":"Hello from iPhone"}

Inspect the current identity

GET /api/v1/session

The response separates the browser session from the host process: session.role is management-device, while relayNode.role is relay-node. Relay metadata can also be read with:

GET /api/v1/node

Loopback management sessions have owner access and can create or revoke pairings. Paired remote management devices remain scoped to their own transfers.

List or clear clipboard history

GET /api/v1/history?limit=50
DELETE /api/v1/history
DELETE /api/v1/history/<entry-id>

Windows loopback requests can manage every entry. A paired device is limited to transfers involving its own device identity.

Discover targets and route text

GET /api/v1/peers
POST /api/v1/transfers
Content-Type: application/json

{"kind":"text","text":"Hello everyone","targetIds":["<relay-node-id>","<iphone-id>","<mac-id>"]}

The v0.4 windows-host target remains a compatibility alias for whichever relay node is currently active.

Read or clear the current device inbox

GET /api/v1/inbox
DELETE /api/v1/inbox/<transfer-id>
DELETE /api/v1/inbox

Inbox endpoints are target-scoped: one paired device cannot inspect or consume another device's pending transfers.

Send and receive files

Upload a raw file body with one or more repeated targetId values and the display name in the query string. The body is stored once even when several targets are selected:

POST /api/v1/file-transfers?targetId=<iphone-id>&targetId=<mac-id>&name=photo.jpg
Content-Type: image/jpeg

<raw file bytes>

The target lists and clears only its own file inbox:

GET /api/v1/file-inbox
DELETE /api/v1/file-inbox
DELETE /api/v1/file-transfers/<file-id>

The sender can inspect independent delivery state for its recent shared Blobs:

GET /api/v1/file-outbox

POST /api/v1/file-transfers/<file-id>/download creates a 60-second, single-use download URL. The URL contains no device key. Add ?inline=1 to request a safe browser preview when that file type supports it.

Health check

GET /health

Release status and roadmap

• 0.2.0: Device identity, one-time pairing, QR pairing, device management, and revocation.
• 0.2.1: Local clipboard history with source and target devices, timestamps, a 50-entry limit, replay/copy, and scoped clear controls.
• 0.3.0: Local multi-device routing, named destinations, target-isolated inboxes, and a browser/PWA experience for Mac and mobile devices.
• 0.4.0: Streamed local file relay, device-scoped file inboxes, safe previews, single-use downloads, quotas, and automatic expiry.
• 0.4.1: One-to-many text/file sending, shared Blobs, and independent per-recipient delivery status.
• 0.5: Native Mac relay client with explicit management-device and relay-node roles. Released and verified on Mac hardware.
• 0.6: Experimental HTTPS PWA and WebRTC online direct transfer. Released; feature development paused after usability evaluation.
• 0.7 (current): Agent Handoff Beta with GitHub account and repository discovery, safe clone/update flows, registered sending and receiving computers, explicit role-based UI, and portable Markdown/JSON/patch packages. See the Agent Handoff guide.
• Later: End-to-end encrypted offline relay, revisited only when a concrete workflow requires it.

Development

npm install
npm test

ClipBridge is available under the MIT License.