Seamsync

Sync a vault across devices through a cloud storage service.

Seamsync is an Obsidian plugin that keeps one person's vault the same on all of their devices, desktop and mobile. This release syncs through Dropbox.

Features

• Dropbox, App Folder access. The plugin reaches only Apps/<app folder name> in Dropbox. Each synced vault (a Remote) is a subfolder there, chosen or created when you connect. It asks for the files.metadata.read, files.content.read, files.content.write and account_info.read scopes and nothing else.
• A plain mirror. The Remote holds the vault's files at the same paths, readable in Dropbox itself. The plugin's own data lives in one .seamsync folder there; do not modify it.
• Automatic sync. Seamsync syncs when the vault opens, after an edit once the post-edit pause has passed, on a polling interval while Obsidian is open, when the app becomes visible and when the network comes back. Offline, it retries quietly with backoff.
• Text merge. Concurrent edits to text files are merged line by line against the last synced version. Lines both devices changed become conflict blocks (<<<<<<<, =======, >>>>>>>) that you resolve in the editor: keep one side, keep both, or edit.
• Conflict copies. A file that cannot be merged, such as an image or a PDF, keeps the other device's version at its path, and this device's version is kept next to it as Name (conflict <device name> YYYY-MM-DD HHmm).ext.
• Deletion guard. A sync that would delete more than a set number or share of files on either side pauses and asks first. The first sync never deletes anything and shows a preview before it starts.
• Configuration folder sync, opt-in. Settings and hotkeys, themes and snippets, and plugins each sync only if you turn them on. The workspace layout never syncs. Other plugins' settings may hold secrets, which are then copied to Dropbox.
• Shared settings. An ignore list in .gitignore syntax, the extensions treated as text, the size limit and how to handle names Dropbox cannot store apply to every device.
• Sync window. Conflicts, skipped files, an activity log with a "Copy for a bug report" action, and help.
• Languages. English and Russian, chosen from Obsidian's language.

Dot-files and dot-folders such as .git and .trash never sync, except the configuration folder categories you turn on.

Disclosures

• Network use. Seamsync sends the vault's files over the network to your Dropbox, and downloads from it the files your other devices synced. Its only network requests go to Dropbox.
• Dropbox account. Seamsync needs a Dropbox account: without one, it cannot sync.
• Vault enumeration. Seamsync lists every file and folder Obsidian shows in the vault, and everything in the configuration folder, because it syncs the whole vault: each sync compares this list with the Remote and the sync snapshot to find what changed. Listing is not syncing: configuration categories you have not turned on are listed but not synced.
• Clipboard. Seamsync only writes to the clipboard, and only when you select Copy error in the connect window or Copy for a bug report in the sync window. It never reads the clipboard.

Installation

Seamsync is not in the Obsidian community plugin list. To install it, download main.js, manifest.json and styles.css from a release of this repository and copy them into <vault>/.obsidian/plugins/seamsync/, then enable Seamsync in Settings → Community plugins. A build from source (see Development) connects to Dropbox only when it is built with SEAMSYNC_DROPBOX_APP_KEY set.

It needs Obsidian 1.11.4 or later.

Usage

1. Open Settings → Seamsync and select Connect.
2. Select Open Dropbox, allow access, copy the code Dropbox shows and paste it into the Code field.
3. Choose an existing folder or create a new one, and name this device.
4. Read Before you sync, review the first sync preview and start it.

Repeat on every other device, choosing the same folder.

The refresh token is kept in Obsidian's secret storage on the device. It is not written to the vault, to the plugin's data.json or to Dropbox. Disconnect revokes it.

Commands

On desktop the status bar shows the sync state; on mobile a ribbon icon does. Selecting it opens the sync window.

Settings

This device only:

All devices, stored on the Remote and saved with Apply to all devices:

How it works

The design is recorded in docs/adr/ and the terms in GLOSSARY.md:

• ADR 0001: the sync engine talks to storage only through a provider contract; Dropbox is the one provider built.
• ADR 0002: the Remote is a plain mirror, and changes are found by comparing its listing or change feed with each device's own snapshot.
• ADR 0003: device journals for providers without conditional writes. This is the design only; this release does not build it, and Dropbox uses conditional writes.
• ADR 0004: Dropbox App Folder access instead of Full Dropbox.
• ADR 0005: a build from source has no Dropbox app key and cannot connect; releases are built by a GitHub Actions workflow, which attests main.js and styles.css.

Development

Tools: Node.js, pnpm, lefthook, gitleaks, typos, shellcheck and shfmt, at the versions pinned in mise.toml. With mise:

mise install

pnpm install --frozen-lockfile

lefthook install

mise run setup-dev does all three.

A dev container is provided in .devcontainer/.

The build bundles a Dropbox app key, which is never committed. Set SEAMSYNC_DROPBOX_APP_KEY in the environment or in a git-ignored .env file. A build without it succeeds with a warning, but cannot connect to Dropbox: its connect window says so. The app must have App Folder access.

mise run check runs every check that changes nothing.

The git hooks (lefthook.yml) check:

• pre-commit: formats the staged files (Prettier, shfmt), then scans them for secrets (gitleaks), spelling, Markdown and shell lint, and runs the type check, lint and tests;
• commit-msg: Conventional Commits, subject up to 50 characters, body lines up to 72, and no Claude Code session link;
• pre-push: the build, the tests with coverage, knip, pnpm audit, and a secret scan of the commits being pushed.

Releases are built by the GitHub Actions workflow .github/workflows/release.yml, started by pushing a tag equal to the version in manifest.json and package.json (X.Y.Z, no v prefix). It takes the key from the repository's Actions secret SEAMSYNC_DROPBOX_APP_KEY, which the maintainer creates in the repository's settings, and stops when that secret is unset or empty, attests main.js and styles.css, and creates a draft release, which the maintainer publishes by hand.

Testing

• pnpm test runs the unit tests and the tests of the whole plugin on a fake vault and a fake Dropbox: no network, no Obsidian. The pre-commit hook runs it.
• pnpm test:e2e:desktop, pnpm test:e2e:android and pnpm test:e2e:pair drive a real Obsidian on the desktop and on an Android emulator. They run on Linux only and need a setup done once: see test/e2e/README.md.

License

MIT