If you’re reading this, someone sent you a link because they want to set up a shared folder with you. This takes about 5 minutes.

Quick Start (Claude Code)

If you use Claude Code, paste this into your terminal:

Can you help me set up a shared Syncthing folder? Here's the guide: https://hedwards.dev/shared-knowledge-sync/

Claude will walk you through it. Skip to What You’re Setting Up if you want context first.

Quick Start (Terminal)

Everything below is safe to re-run. If a command says something “already exists”, that step was already done — maybe from a previous setup with someone else. Skip it and move on.

  1. Install Syncthing (if you haven’t already)

    • macOS: brew list syncthing 2>/dev/null || brew install syncthing then brew services restart syncthing
    • Linux: sudo apt install syncthing && systemctl --user enable --now syncthing
    • Windows: winget install --exact --id GermanCoding.SyncTrayzor — this installs the maintained SyncTrayzor v2 tray app, which bundles Syncthing. Open SyncTrayzor once after installation. If syncthing isn’t recognised in the terminal, use the bundled executable; for a current-user install, the bundled copy is typically at %LOCALAPPDATA%\Programs\SyncTrayzor\syncthing.exe.

  2. Get your Device ID and send it to your friend (they send you theirs the same way):

    syncthing device-id

    If that errors with unexpected argument you’re on Syncthing 1.x (common with distro-archive installs — Ubuntu’s own repo ships 1.29.x, while Syncthing’s apt repo ships 2.x). Use this instead and read the myID field:

    syncthing cli show system

    Either way it’s a long string like XXXXXXX-XXXXXXX-XXXXXXX-.... Device IDs aren’t secret — they only work once both sides add each other.

  3. Add your friend’s device:

    syncthing cli config devices add --device-id 'THEIR-DEVICE-ID' --name 'Friend Name'

  4. Create the folder and share it. Agree on a Folder ID with your friend first (e.g. shared-harrison-alice) — it must match exactly on both sides, and it is case-sensitive, so shared-harrison-alice and Shared-Harrison-Alice are two different folders that will never pair. The folder path can differ between you; only the ID matters.

    Is the shared folder going inside a vault — or any parent folder — that Syncthing already manages? Stop before running these commands. First exclude the shared subfolder in the parent folder’s .stignore, then add it as an independent Syncthing folder. Otherwise you create an unsupported nested-folder setup that can cause sync conflicts. Follow If Your Vault Is Already a Syncthing Folder first.

    mkdir -p "$HOME/Notes/Shared - Friend"
syncthing cli config folders add --id 'shared-harrison-alice' --label 'Shared - Friend' --path "$HOME/Notes/Shared - Friend"
syncthing cli config folders shared-harrison-alice devices add --device-id 'THEIR-DEVICE-ID'

    Put the folder wherever you like — inside your Obsidian vault is the usual spot. Just use the same path in both commands.

  5. Verify pairing and completion:

    syncthing cli config folders list
syncthing cli show pending folders
curl -s -H "X-API-Key: $(syncthing cli config gui apikey get)" \
  "http://localhost:8384/rest/db/completion?folder=AGREED-FOLDER-ID&device=THEIR-DEVICE-ID"

    Pass only when the folder list contains the agreed ID, pending folders returns {}, and the completion response shows remoteState as valid, completion as 100, needItems and needBytes as 0, and no remote errors. A connected device or a listed local folder alone does not prove the two sides paired. The web UI should agree: the device is connected, the folder is Up to Date, and no failed or out-of-sync items remain.

If one of you already has files in the folder, they’ll sync across once you’re both online. That’s expected.

Quick Start (Web UI)

Prefer clicking to typing? Same setup via the web UI at http://localhost:8384:

Is the shared folder going inside a vault — or any parent folder — that Syncthing already manages? Stop before step 4. First exclude the shared subfolder in the parent folder’s .stignore, then add it independently. Follow If Your Vault Is Already a Syncthing Folder first.

  1. Install Syncthing as in step 1 above

  2. Get your Device ID: Actions (top right) → Show ID. Send it to your friend.

  3. Add your friend’s device: Add Remote Device → paste their ID → Save

  4. Create a folder in your Obsidian vault called Shared - [Friend's Name]/

  5. Add the shared folder: Add Folder → set Folder ID to something you both agree on (e.g., shared-harrison-alice) → select the folder you created → Sharing tab → check your friend’s device → Save

    Watch the Folder ID field here. The web UI fills it in from the label you type, which usually capitalises it, and the ID is case-sensitive. Set it explicitly to the agreed ID rather than accepting the auto-filled value, or your folder will not pair with your friend’s.

Your friend does the same on their end. If they set up first, Syncthing may instead prompt you to accept a shared folder — confirm and set the local path. Do not treat a merely connected device as completion: the folder must show Up to Date on both sides, with no pending folder offer and no failed or out-of-sync items; use Terminal step 5 for the exact pairing/completion check.

macOS Permissions (Optional but Faster)

Not strictly needed — Syncthing connects through relay servers without any firewall changes. But allowing direct connections is faster:

  1. Firewall: System Settings → Network → Firewall. If it’s on, make sure syncthing is in the allow list.
  2. Local Network: If a popup asks “Allow syncthing to find devices on your local network?” — click Allow.

What You’re Setting Up

Syncthing keeps folders in sync between computers - like Dropbox, but peer-to-peer with no cloud server in the middle. Free, open source, runs locally. Traffic is end-to-end encrypted regardless of how the two machines connect.

When you save a file, it appears on your friend’s computer within seconds (as long as you’re both online). If one of you is offline, changes queue up and sync when you reconnect.

What goes in the shared folder:

  • Prompts that worked well
  • CLAUDE.md snippets worth reusing
  • Workflow discoveries
  • Async questions for each other

What stays out:

  • Anything you wouldn’t share with this person
  • Personal vault content (the rest of your vault isn’t affected)

If Your Vault Is Already a Syncthing Folder

If the folder you’re sharing lives inside a folder Syncthing already manages — say your whole vault already syncs to a NAS or a second machine — don’t just add the subfolder as a new Syncthing folder. Nested folders are unsupported (the maintainers’ words: “not supported, not recommended, not coded for”), and double-management causes sync conflicts.

Exclude the subfolder from the parent first, then add it independently:

  1. Add the subfolder to the top of the parent folder’s .stignore, before any ! include patterns — the first matching pattern wins, so if an include matches first, the exclusion won’t fire:

    // Shared folders managed independently (not via the parent folder)
Shared - Friend/**

  2. Before creating the independent folder, verify Syncthing loaded that rule for the parent folder:

    curl -s -H "X-API-Key: $(syncthing cli config gui apikey get)" \
  "http://localhost:8384/rest/db/ignores?folder=PARENT-FOLDER-ID"

    Pass only when the response’s ignore list shows Shared - Friend/** before every matching ! rule and its expanded list contains the shared path. If either check fails, fix .stignore and rescan the parent; do not create the nested folder yet.

  3. Then add the subfolder as its own Syncthing folder, as in the Quick Start.

The parent folder stops managing that path; the new shared folder takes over.

Syncing an Entire Vault

The guide above covers a shared subfolder inside your vault - good for swapping prompts and tips while keeping your vaults separate. But if you want to work from the same vault (e.g., a family or team knowledge base), Syncthing handles that too.

Setup is the same - just point Syncthing at the vault root instead of a subfolder. The one difference is you’ll want a .stignore file in the vault root to avoid stepping on each other’s Obsidian settings:

// .stignore - place in the vault root
// Each person's Obsidian config stays independent

.obsidian/workspace.json
.obsidian/workspace-mobile.json
.trash/

workspace.json tracks which panes/files are open - without ignoring it, opening a note on one machine rearranges the other person’s layout. .trash/ is Obsidian’s soft-delete folder; syncing it causes deleted files to reappear.

If you also want independent plugin configs, hotkeys, or themes, add:

.obsidian/plugins/
.obsidian/hotkeys.json
.obsidian/appearance.json

Otherwise leave those out and you’ll share a consistent setup - useful when one person is managing the vault config for both.

Conflicts are more likely with a shared vault than a shared subfolder, since you might both edit the same note. See Conflicts below - Syncthing creates .sync-conflict files rather than overwriting, so nothing is lost.

For Claude Code

This section helps Claude Code guide you through setup. You can skip it.

Installation Commands

macOS (Homebrew - recommended):

brew list syncthing 2>/dev/null || brew install syncthing
brew services restart syncthing

macOS (standalone): Download from syncthing.net/downloads, move to Applications, open. Grant folder access when prompted. If macOS blocks it: System Settings → Privacy & Security → Open Anyway.

Linux (apt-based):

sudo apt install syncthing
systemctl --user enable --now syncthing

Windows:

winget install --exact --id GermanCoding.SyncTrayzor

This installs the maintained SyncTrayzor v2 tray app, which bundles Syncthing. Open SyncTrayzor once after installation. If syncthing isn’t on PATH, invoke its bundled executable; for a current-user install, the bundled copy is typically at %LOCALAPPDATA%\Programs\SyncTrayzor\syncthing.exe.

After installation, the web UI is at http://localhost:8384

Verifying Installation

Check if Syncthing is running:

# Linux
systemctl --user status syncthing

# macOS (Homebrew)
brew services list | grep syncthing

# Any platform - if this returns JSON, it's running
curl -s http://localhost:8384/rest/system/status | head -c 100

Getting the Device ID

In the web UI: Actions (top right) → Show ID

Or via CLI:

# Syncthing 2.x (simplest, no running instance needed)
syncthing device-id

# Syncthing 1.x (e.g. Ubuntu/Debian distro-archive builds — `device-id` doesn't exist there;
# requires the running instance)
syncthing cli show system   # read the myID field

Check which with syncthing --version before choosing.

The Device ID is a long string like XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX. This is what you exchange with your friend.

Configuring via CLI

The syncthing cli config commands in the Quick Start are the preferred path — they’re idempotent-friendly (an “already exists” error means the step is done; skip it) and need no clicking:

syncthing cli config devices add --device-id 'THEIR-DEVICE-ID' --name 'Friend Name'
syncthing cli config folders add --id 'AGREED-FOLDER-ID' --label 'Label' --path '/path/to/folder'
syncthing cli config folders AGREED-FOLDER-ID devices add --device-id 'THEIR-DEVICE-ID'
syncthing cli config folders list

Notes:

  • Folder ID must match on both computers, and it is case-sensitive. The folder name and path can differ - only the ID matters. Agree on an ID before starting (e.g., shared-harrison-alice).
  • The local device is added to new folders automatically.
  • Paths can contain spaces.
  • Both sides must add each other’s device before anything syncs.
  • If the user’s vault root is already a Syncthing folder, apply the parent .stignore exclusion first (see If Your Vault Is Already a Syncthing Folder).

Folder location

Inside the Obsidian vault, e.g.:

  • ~/Notes/Shared - Harrison/
  • /mnt/nas/Files/05 Resources/Shared - Alice/

The exact path depends on where the user’s vault lives.

Folder Structure Suggestions

Shared - [Friend's Name]/
├── Prompts/
│   └── [dated or descriptive names].md
├── Discoveries/
│   └── 2026-01-23 - Thing I found.md
├── CLAUDE.md Snippets/
│   └── [reusable context sections].md
└── Questions.md   # async back-and-forth

Conventions that help:

  • Prefix files with your initials if you’re both adding to the same subfolder
  • Date discoveries so the timeline is scannable
  • When adding a prompt, include context: what it’s for, when it works, caveats

Troubleshooting

Not connecting after a few minutes?

  • Is Syncthing running? Linux: systemctl --user status syncthing. macOS: brew services list | grep syncthing — should say started; if not, brew services restart syncthing.
  • Can you see the web UI? Open http://localhost:8384 — if this doesn’t load, Syncthing isn’t running.
  • Did both sides add each other? Your friend’s device must be added on your side and yours on theirs, and the folder shared with the device on both ends.
  • Folder IDs match? syncthing cli config folders list on both machines — the IDs must be identical.
  • Both machines online? Sync only happens while you’re both up. Changes queue when offline.
  • Firewall: Not required — relays work through it — but allowing syncthing enables faster direct connections.
  • Give discovery a moment: First connection via global discovery/relays can take a couple of minutes.
  • A ~/Sync folder appeared? Syncthing auto-creates a stock “Default Folder” there on first run. It’s shared with nobody and syncs nothing — ignore it, or remove it from the folder list.

Edge Cases

Conflicts

If you both edit the same file at the same time, Syncthing creates a .sync-conflict file rather than overwriting. This is rare - you’re typically adding new files, not editing the same one simultaneously.

If it happens often, switch to append-only: each person has their own files, you read each other’s rather than co-editing.

Git Integration

Whether to git-track the shared folder depends on what your vault repo is for.

Private auto-save/backup repo (never pushed)? Leave the shared folder tracked. Your friend’s synced changes get committed alongside yours, which gives you free point-in-time recovery of the shared content — and commit attribution is already meaningless in an auto-save repo, so nothing is muddied.

Repo that’s pushed anywhere, or a hand-curated history? Exclude the shared folder:

Shared - */

Pushing a repo that tracks the shared folder publishes your friend’s content along with yours, and in a curated history, commits that silently absorb their Syncthing-delivered changes confuse authorship.

If you want dedicated version history for shared content, you can initialise a separate git repo inside the shared folder — but first add .git to the shared folder’s .stignore on both sides. Without that, the repo itself syncs across: your friend receives your entire commit history, and if you both commit, the two .git directories corrupt each other.

cd "Shared - Friend/"
printf '.git\n' >> .stignore
git init
git add -A
git commit -m "Initial shared knowledge base"

Privacy

Everything in the shared folder is visible to your friend. Use Syncthing’s .stignore file if you need to exclude specific files from sync.

Offline Behaviour

Both computers need to be online simultaneously for sync to happen. If your friend’s laptop is off, changes queue up and sync when they reconnect. No data is lost - just delayed.