db-sync

A Claude Code skill that syncs one SQLite/libSQL database across two or more machines — so you can run Claude Code (or any app) on several computers and have them share one database that stays in step and cannot collide. Deterministic, collision-safe, and driven entirely by prompting.

System-agnostic: no hard-coded project, owner, or machine. You point it at a database file and a primary name, and it does the rest. Built on Turso / libSQL embedded replicas — free tier.

How two machines share one database

There is one logical database, realised as:

• one cloud primary — the single source of truth, and
• one local replica file per machine — fast local reads, offline-capable.

Each machine syncs only with the primary, never with the other directly. A write on machine A goes up to the primary; machine B pulls it down on its next sync; both converge to the same state. Two local copies, one shared database.

Commands

Command	Purpose
/db-sync setup	One-time, on the machine holding the canonical database: seed the cloud primary from the existing file, swap the connection to an embedded replica, add unique IDs + a flock guard + a sync cadence, install the command and timer.
/db-sync onboard	On each other machine: make it a replica of the same primary.
/db-sync now	Push local writes up, pull the other machines' down.
/db-sync status / doctor	Last-sync age, replica health, credential and file-sync-folder checks.

Why it is deterministic and can't collide

• Online-write mode only — every write routes to the single cloud primary, which serialises them into one total order. Two machines writing at once is safe; the primary is the one referee, and every replica converges to the same state.
• Globally-unique IDs (ULID / UUIDv7) — two machines can never mint the same key.
• Per-machine flock — two local processes never open the replica mid-sync.
• Offline-writes mode is deliberately not used (its last-push-wins resolution can drop a write).

Install

bash scripts/install.sh          # links the skill into ~/.claude/skills + a `db-sync` command
bash scripts/install.sh --timer  # also load a launchd timer that syncs every 5 minutes

Then run /db-sync setup on the machine that holds the database, and /db-sync onboard on the others.

Layout

SKILL.md                            the skill (setup / onboard / now / status / doctor)
scripts/db_sync.py                  standalone, flock-guarded sync engine
scripts/db-sync                     CLI wrapper
scripts/com.dbsync.db-sync.plist    launchd timer template (sync every 5 min)
scripts/install.sh                  installer
references/setup.md                 the one-time migration runbook
references/connection-template.py   the libSQL embedded-replica connection pattern
references/buttons.md               Raycast / SwiftBar "sync now" button snippets

Safety

Credentials live in a gitignored env file (~/.config/db-sync/db-sync.env), never in the repo. The local replica must live outside any cloud file-sync folder (Drive / Dropbox / iCloud), which corrupts live databases. Free tier only.

Requirements

• A free Turso account and the Turso CLI.
• Python 3 with the libsql client (pip install libsql).
• macOS for the launchd timer (the skill itself is cross-platform).