VSCollab

A first VS Code extension for sharing one workspace folder through your own WebSocket relay. The host shares text files, guests open temporary local copies, and edits to those files sync through Yjs.

Test with a friend

Install VSCollab on both computers from the Marketplace, or install VSCollab-0.1.0.vsix with Extensions: Install from VSIX. The host can start the relay from the installed extension; no source checkout or separate Node.js installation is needed for that route.

1. Put a small, disposable text project in a folder on the host computer. Keep a copy or commit before testing.
2. On the host, open the VSCollab Activity Bar view and select Start local relay. Choose the LAN IPv4 address your friend can reach. VSCollab fills the Relay server field with ws://<host-LAN-IP>:8787. Keep this VS Code window open while sharing.
3. If you are in different locations, use a private network such as Tailscale. You can share just the host computer with your friend. After both computers can reach each other, bind the relay to the host's Tailscale IPv4 address instead: HOST=<host-Tailscale-IP> npm run server on macOS/Linux, or $env:HOST='<host-Tailscale-IP>'; npm run server in PowerShell. Set Relay server to ws://<host-Tailscale-IP>:8787. Do not expose this prototype's plain WebSocket port directly to the public internet.
4. Open the project folder in the host's VS Code, enter a name in the VSCollab view, and select Share this workspace. Send the copied invite link only to your friend.
5. On your friend's computer, open a new empty VS Code window, open the VSCollab view, enter a name, paste the invite link, and select Join workspace. VS Code adds a VSCollab folder in Explorer. Open a shared text file on both computers to check the cursor labels, then edit it on either side and confirm the change reaches the other side and the host's disk folder.
6. For an AI test, run Codex against the host's original folder and Claude Code against the friend's new local VSCollab folder. Have each tool edit a different small text file first, and confirm both files update on both computers. The AI tools need to target those folders explicitly; VSCollab does not connect their chats.

The guest's VSCollab folder is created under that computer's operating-system temporary directory. It is a local copy, not a remote mount. The relay forwards Yjs updates between the copies. When the guest edits a shared file, the host extension updates the original folder on the host computer. The host and guest must keep VS Code and the relay running for live syncing. The relay keeps session state only in memory.

If joining fails, first open http://<host-IP>:8787 in a browser on the friend's computer. It should show VSCollab relay is running. If it does not, check the IP address, firewall, network access, and that the host's VS Code window is still open.

How to run it

1. Run npm install and npm run build in this folder.
2. Start the relay with npm run server in a terminal. It listens at ws://127.0.0.1:8787 by default. For LAN access, use HOST=0.0.0.0 npm run server on macOS/Linux or $env:HOST='0.0.0.0'; npm run server in Windows PowerShell.
3. Open this folder in VS Code and press F5. This opens an Extension Development Host window.
4. In that window, open the folder you want to share and select the VSCollab icon in the Activity Bar. Enter your name and relay address, then choose Share this workspace. The invite link is copied to your clipboard.
5. In another VS Code Extension Development Host window with this extension loaded, open the VSCollab view, enter your name, paste the invite link, and choose Join workspace. Open the new VSCollab folder in Explorer.

For internet access without a private network, a TLS reverse proxy and wss:// would be required. That deployment has not been tested for this prototype.

Run npm run check for TypeScript validation and npm test for the relay integration test. To package it for installation, run npx @vscode/vsce package after setting your Marketplace publisher ID in package.json.

What this version does

• Shares up to 500 UTF-8 text files, each at most 1 MiB and totaling at most 20 MiB, from one folder.
• Excludes .git, node_modules, dist, build, .venv, .next, .env*, and common private-key files.
• Uses a random room ID and secret in the invite link. Anyone with the link can edit the shared files.
• Shows connected collaborators by name. The host can remove guests and pause or resume new joins from the VSCollab sidebar. Pausing joins does not disconnect existing guests.
• A removed guest can rejoin with the same invite link while joins are open. Pause joins to block that link temporarily.
• Shows each collaborator's cursor and selection in shared text editors with a name and color. Cursor positions use Yjs relative positions so they move with nearby edits.
• Watches shared files for external changes. Codex, Claude Code, or another tool can edit, create, rename, or delete eligible text files in either person's local shared folder; the changes are sent to the other person. Edits made in VS Code are saved to disk so local AI tools can read them.
• Keeps the relay state in memory only. A session ends when the host disconnects.

Current limits

• Binary files, per-person edit permissions, and an indicator for which file each person is editing in the sidebar are not implemented. All connected guests can edit shared text files.
• Guest files are local temporary copies. They remain on disk after leaving, and the user should close the guest folder before starting another session.
• The guest copy does not include excluded folders such as .git or node_modules. AI tools can edit the shared source files there, but running builds or Git commands may require a separate project setup. Each person should point their AI tool at the local VSCollab folder they are editing.
• VSCollab syncs file changes; it does not connect Codex or Claude Code to each other or coordinate their prompts, terminal commands, or decisions. Each person runs their own AI tool in their own local shared folder.
• An external disk change is skipped while that same file has unsaved changes open in VS Code. Save or resolve the local document first. Large whole-file rewrites to the same file by multiple AI tools at once can still produce confusing merges; coordinate those changes before relying on this for important work.
• The relay is a development prototype: there are no user accounts, rate limits, durable storage, or audit logs. Plain ws:// does not encrypt traffic.
• VS Code receives remote edits through WorkspaceEdit. Rapid simultaneous edits to the same region should be tested more thoroughly before relying on this for important work.
• Only the VS Code desktop extension host is supported; this is not a browser extension.

How a VS Code extension works

package.json is the extension manifest: it declares the commands, settings, minimum VS Code version, and compiled entry point. src/extension.ts registers the commands and listens for document changes through the VS Code API. src/server.ts is a separate relay process. npm run build bundles both. VS Code launches the extension code when a user invokes a command. Pressing F5 opens a second VS Code window for debugging the extension.