scratch-sync

Sync private scratch/ folders across multiple machines using Syncthing over Tailscale.

The Problem

Working across multiple machines (Linux workstation, Mac laptop, Windows desktop) with code repositories in different locations:

Each repo has a scratch/ subfolder that's .gitignored — notes, experiments, temp files, WIP that shouldn't be in version control but should sync privately across machines.

Solution

• Sync scratch/ folders without git
• Single CLI command to add folders to sync
• Works across Linux, macOS, and Windows
• Uses Tailscale for secure direct connections (no cloud relay)
• Minimal ongoing maintenance

Quick Start

Prerequisites

• Tailscale installed and connected on all machines
• All machines on the same Tailnet

Install

macOS / Linux:

curl -LsSf https://scratch.tlab.sh/install.sh | sh

Windows (PowerShell):

iwr -useb https://scratch.tlab.sh/install.ps1 | iex

The installer will download Syncthing, set up auto-start, and show you the status of all dependencies:

Dependencies

  uv           installed 0.9.18     ~/.local/bin/uv
  tailscale    running   1.92.3     your-tailnet.org / you@example.com
  syncthing    running   v2.0.12    ~/.local/bin/syncthing / autostart: launchd

After installation, remember to set up a password for the Syncthing dashboard at http://127.0.0.1:8384/.

Uninstall (macOS / Linux):

curl -LsSf https://scratch.tlab.sh/install.sh | sh -s -- --uninstall

Uninstall (Windows):

$env:UNINSTALL=1; iwr -useb https://scratch.tlab.sh/install.ps1 | iex

Check dependency status:

curl -LsSf https://scratch.tlab.sh/install.sh | sh -s -- --status

Install the CLI

The scratch-sync CLI helps you manage synced folders. Choose your preferred installation method:

Permanent install (recommended):

uv tool install scratch-sync

This installs scratch-sync globally so you can run it from anywhere.

Run without installing:

uvx scratch-sync --help

If you prefer not to install permanently, use uvx to run the latest version on-demand.

Update to latest version:

uv tool upgrade scratch-sync

Uninstall:

uv tool uninstall scratch-sync

Usage

# Inside a git repo with a scratch/ folder
scratch-sync init

# Add a specific scratch folder
scratch-sync add ~/code/myrepo/scratch

How It Works

Syncthing folder IDs just need to match across devices. The actual filesystem paths can be different:

• scratch-sleap-io on Linux at ~/code/sleap-io/scratch
• Same folder ID on Windows at D:\sleap-io\scratch

┌─────────────────┐     Tailscale      ┌─────────────────┐
│  Linux Box      │◄──────────────────►│  Mac Laptop     │
│ ~/code/sleap-io │                    │ ~/sleap-io      │
│   └── scratch/  │   folder-id:       │   └── scratch/  │
│                 │  "scratch-sleap-io"│                 │
└────────┬────────┘                    └────────┬────────┘
         │            Tailscale                 │
         └──────────────┬───────────────────────┘
                        ▼
              ┌─────────────────┐
              │  Windows PC     │
              │ D:\sleap-io     │
              │   └── scratch/  │
              └─────────────────┘

Documentation

Full documentation at scratch.tlab.sh.

Development

Setup

Clone the repository and install dependencies:

git clone https://github.com/talmolab/scratch-sync.git
cd scratch-sync
uv sync

This creates a virtual environment and installs all dependencies.

Running in development

Run the CLI directly from source:

uv run scratch-sync --help

Install from GitHub

Install the latest development version from the main branch:

uv tool install git+https://github.com/talmolab/scratch-sync.git

Or run without installing:

uvx --from git+https://github.com/talmolab/scratch-sync.git scratch-sync --help

Local editable install

For development, install as an editable tool from your local checkout:

uv tool install --editable .

This installs scratch-sync globally but uses your local source files, so changes take effect immediately.

To uninstall and reinstall after making changes to entry points:

uv tool uninstall scratch-sync
uv tool install --editable .

License

MIT