the lab
∮project

Locust

A small offline-first reading client that syncs across devices via CRDTs — a testing ground for ideas in Local-First Software.

active since June 2025 local firsttools for thought

Locust is the ugliest of my projects and, so far, the one I learn the most from. It’s a stripped-down reader for long-form articles that keeps the canonical store on-device and treats the network as a sync channel rather than a source of truth.

I started it after a transcontinental flight where my “cloud-native” reader bricked itself for the entire flight because the auth token expired mid-takeoff. An indignity I plan to write a longer essay about, eventually. The fix is structural, not patchy.

The current focus is the conflict surface: when two devices have diverged because both were offline for a week, what does the merged view look like? Not the data structure — the merged view as a thing the user sees and acts on. See the running thread in Merge conflicts as design.

River

  1. Sep 25, 2025 Should the seam fade? question After a merge becomes visible, when (if ever) does the visible seam disappear?
  2. Sep 22, 2025 Merge conflicts as design post Most CRDT writeups stop where the design problem starts — what does the merged document look like to a human?
  3. Sep 8, 2025 First sync between phone and laptop timeline-entry A two-character edit on the phone showed up on the laptop in roughly 800ms over a hotel wifi. Embarrassingly, this felt momentous.
  4. Aug 4, 2025 Sync architecture sketch note Working notes on the sync layer. SQLite + a tiny relay; CRDT on top; end-to-end encrypted.

Pointed at by

Should the seam fade? — “…lt. I don't know yet. I want to try the third in Locust and see whether it's annoying in practice.…” read

Merge conflicts as design — “…ll log of merge-shaped weirdness while dogfooding Locust: 1. **Two devices both edit the same paragraph.*…” read

Sync architecture sketch — “…ll essay version, when it arrives, should live in Locust. ## Storage - **Local**: SQLite with WAL. One fi…” read

October planning meeting — “…first prototype. (Not the same as forever; see Locust for the sync ideas.) ## Tasks <Tasks> <Task d…” read

Andy Matuschak — “…es are *not* evergreen and shouldn't be promoted. Locust is downstream of the *attention* point — a reader…” read