Tether help & troubleshooting

This guide covers sign-in, shared files, access and recovering work when something goes wrong.

Getting Started

Open the Tether sidebar from the Activity Bar. If the icon is missing, run Tether: Open Tether from the Command Palette. Press Ctrl+Shift+P (Cmd+Shift+P on macOS) and type Tether to find the available commands.

1. Select Sign In, choose GitHub, Microsoft or Google, and choose a Tether username if prompted.
2. To share a folder, select Create Project under My Projects. Review the files before confirming, then use Invite People to invite teammates by username or create an invitation link. Invite links expire automatically after 30 days. Choose Member or Observer access, confirm, then copy and share the link.
3. To join, accept an invitation under Invitations, or open an invitation link and confirm in Tether. Click the folder-open icon or project name under Shared With Me and choose where to create the local folder.
4. Open a shared text file to collaborate. Search for Tether in VS Code Settings to adjust auto-save and teammate indicators.

Sign-in problems

Sign-in opens your browser. Finish signing in with the selected provider and allow the browser to return to VS Code when prompted. Keep the VS Code window that started sign-in open.

If sign-in stays unfinished, check whether the browser is waiting for confirmation to open VS Code. Use Tether: Cancel Sign-In to cancel an outstanding attempt, then start Tether: Sign In again.

If Tether cannot check your account, restore your internet connection and click the Tether item in the status bar, or run Tether: Refresh Tether.

If Tether says your extension is too old, update it from VS Code's Extensions view before retrying. If the problem continues, follow Collect logs and report a problem below.

Connection problems

With a project open, check the Tether indicator in VS Code's status bar:

• Connecting means Tether is establishing a connection.
• Reconnecting means Tether is trying again; hover the indicator for the retry information.
• Offline means the project is not connected. Check your network and any message about your session or project access.

Shared text files become read-only while Tether reconnects and synchronises. Wait for the connection to return before editing them. If your session needs checking, click the Tether item in the status bar, or run Tether: Refresh Tether.

If an edit was not shared, copy any unsent work somewhere safe before closing or reopening the file. Do not assume a rejected edit will be sent automatically when the connection returns.

Files or changes are missing

Check that you have opened the correct Tether project and are looking at its connected local folder. A different copy of the same files is not automatically connected to that project.

When connected, click the Tether item in the status bar, or run Tether: Refresh Tether from the Command Palette. It checks the shared files and retries synchronisation. Follow any remaining conflict or incomplete-sync messages.

If a file still is not shared:

• Check whether it is excluded by Tether or the project's .tetherignore rules. Ignored files are never shared.
• Ask the host to review the sharing rules. Only the host can apply changes to the project's .tetherignore; saving that file applies the policy update.
• Check for unsaved changes, file read/write errors, a storage warning or a message that sharing has not finished.
• Confirm that you still have permission to edit the project.

Text files support live editing with cursor positioning and other decorations. Binary files, such as images, synchronize as whole-file versions rather than merging edits, and thus do not have the same decorations. Avoid switching Git branches or checking out commits while connected: the resulting file changes can be shared with your teammates.

Permissions and project access

The host and Members can edit shared files. Observers can view shared files and read comments, but cannot edit shared content or reply to comments. New File, New Folder and Paste are disabled in an observer's project folder. Ask the host to change your role if you need editing access.

If you were removed from a project, or it was deleted, reconnecting cannot restore access. Ask the host whether the project is still available and whether you need a new invitation.

If your local folder cannot be read or written, check its operating-system permissions and whether another program has locked the affected file. Preserve local work before retrying an operation that may replace it.

Storage limits

The current shared-content limits are:

Tether can show a storage warning in the status bar. Hover it to see the last reported project usage. Follow the limit reported by Tether; the total size of your local folder, including ignored files, is not the same as shared storage usage.

If a change is refused because a limit was reached, preserve the unsent work first. Reduce the affected shared content or free project space, then follow the message's reconnection or retry instructions. Copy unsent text before closing and reopening its editor. For binary changes, use the recovery steps below when a preserved version is available.

Recover text changes

Edits made outside VS Code, such as by an AI agent, a script or a formatter, sync like a save. If a teammate changed other lines of the same file meanwhile, Tether merges the two. Tether asks first when files changed or were deleted while Tether was off, when git rewrote files, or when a file went back to an older version over a teammate's changes. Choose Share (or Delete) to send the change, or Keep Local (or Restore) to keep it off the shared project.

When your changes to a file conflict with the shared version, Tether keeps your copy and pauses syncing and automatic saving for that file. The file is marked with ! in the Explorer and counted in the status bar. Use Review in the notice, click the status bar item, or run Tether: Resolve Text Conflict…, then choose:

• Merge to edit a result from both versions, published when you choose Apply Merge.
• Use Local to send your copy to the team, replacing their changes since your last sync.
• Accept Shared to replace your copy with the shared version.

Tether first verifies recoverable backups of whatever is replaced. Afterwards, use Compare Backup or Backups to inspect the recovery copies. If there are separate disk and unsaved-editor copies, choose the one you need.

If a choice cannot finish, review the file and any recovery backups before retrying. Check backup storage, file write access, connection and sharing permissions. Recover unsaved editor text before closing or reopening its editor.

Recover binary changes

When Tether reports a preserved binary version, run Tether: Recover Binary Changes while signed in to the account that owns the recovery. Select a preserved version and choose Save Copy.

Choose a new destination outside all active Tether projects. Tether refuses to overwrite an existing destination. Saving the copy keeps the shared version and does not automatically publish the recovered file.

If a binary update is waiting for unsaved editor changes, preserve anything you need before saving or closing the editor to retry. For other failures, fix the problem described in the notice and use Retry when offered.

Discard permanently removes that recovery. Export and check any copy you need before discarding it. If Tether cannot safely save a recovery copy, choose another destination or address the storage or permissions problem, then try again.

Collect logs and report a problem

Run Tether: Show Logs and select a channel:

• Tether contains errors and diagnostics.
• Tether: Activity contains actions and background activity for that VS Code window.

Copy the short interval around the problem. If several windows were involved, collect the relevant logs from each. Review them before sharing: remove credentials, invitation links, private names, local paths and file content.

Ask a question or report the problem on Tether's public Marketplace Q&A page. Include:

• Your Tether extension version, VS Code version and operating system.
• What you were trying to do and the steps that reproduce the problem.
• What you expected, what happened and the exact error message.
• Whether you were the host, a Member or an Observer, and whether the issue affected text or binary files.
• Relevant redacted logs, approximate time and any troubleshooting steps already tried.