Appearance
Cluster Preferences
Clusto can store the app's local user preferences (theme preset, custom CSS, and any other clusto-* localStorage key) on the connected daemon and share them across every client that joins the cluster.
By default every client keeps preferences in its own localStorage - this feature is opt-in: nothing is uploaded until the user clicks Save to cluster, and the cluster blob is never auto-applied to a client until they click Pull from cluster.
Where to configure
Settings → Cluster, card Sync preferences with cluster. The card shows:
- Cluster value updated - the timestamp on the blob the connected daemon currently holds, refreshed automatically on (re)connect.
- Save to cluster - snapshots every
clusto-*key in the running client'slocalStorageand pushes the blob to the daemon. The daemon persists it tocluster_preferences.jsonand, in cluster mode, broadcasts it to every peer. - Pull from cluster - fetches the latest blob from the daemon and compares it with this device first (see below). After you confirm, it replaces every synced
clusto-*key inlocalStorage(keys not in the blob are removed), and reloads the window so module-level composables re-read their state. - Undo last pull - shown after a pull. Puts back the settings this device had before that pull and reloads.
- Refresh - re-fetches the cluster timestamp without touching local state.
The buttons are disabled when no daemon is connected. Sync preferences with cluster in the F1 command palette opens this card.
Pull confirmation and undo
The blob on the cluster may have been saved from a different device (another OS, screen size or input method), and settings that suit that device can make this one slow or hard to use. A pull therefore never writes anything until you confirm:
- The app fetches the blob and diffs it against this device's synced keys.
- If nothing differs, it says so and stops.
- Otherwise a dialog says how many settings it would replace, when the cluster copy was saved, and how many are changed, new or removed, followed by the names of the affected settings (the first eight, then a count). Cancel is the default and leaves everything as it is.
- Replace settings first saves a one-level backup of this device's synced settings under
clusto:cluster-preferences-backup(a key no sync carries), then applies the blob and reloads. If the backup cannot be written, the pull stops with an error instead.
Undo last pull restores that backup and removes it. A newer pull replaces the backup, so only the most recent pull can be undone. Save to cluster has no confirmation: it changes the cluster copy, not this device, and every other device still has to confirm before pulling it.
What gets synced
Everything the app writes under the clusto- localStorage prefix, which today includes:
clusto-theme-preset- selected appearance preset (orcustom).clusto-theme-custom-css- the user's custom CSS overrides.clusto-theme-custom-mode- whether the custom theme is light or dark.- The date and time format chosen in Appearance.
clusto-session-appearance- the session title template, color rules and project overrides from Appearance.
Anything else the app adds under that prefix is picked up automatically.
Device-local keys
Some clusto-* keys describe the device rather than your preferences, so they are never pushed, never applied by a pull, and never deleted by one. Account cloud sync uses the same rule. A blob saved by an older build may still carry them; they are ignored.
- Battery saver (
clusto-battery-*) - when a backgrounded app disconnects. - On-screen keyboard mode (
clusto-terminal-keyboard-mode) - touch devices only. - Panel widths and split ratios (
clusto-nav-width,clusto-right-sidebar-width,clusto-notes-tree-width, the GitHub and Azure DevOps list widths, and the editor, notes editor and design splits), sized for this screen. - What is open on this device: open note tabs and the active tab, the notes tree and folder collapse state, hidden design previews and chat read markers.
- When this device last backed up the notes vault to the cloud.
- Usage-data state (
clusto-telemetry-*): install id, consent and queue.
The retired update-channel preference key is skipped. Keys outside the clusto- prefix are intentionally not synced. The remote-update settings stored at clusto.remoteUpdate.settings.v1 are a notable example: those have their own daemon-side persistence in config.toml and are replicated separately via PeerMessage::SyncRemoteUpdateConfig.
How it's stored and replicated
- The daemon keeps an in-memory
ClusterPreferences { values, updated_at }blob plus a JSON file at<config_dir>/cluster_preferences.json. The file is restored on daemon start, so a restart preserves the last-written value. updated_atis Unix milliseconds, stamped server-side atSettime so a client with a skewed clock cannot poison ordering.- In cluster mode, every
Setis broadcast asPeerMessage::SyncClusterPreferences. Receivers apply the incoming blob only when itsupdated_atis strictly newer than their local copy - last-writer-wins on the whole blob. - Every connected client receives the new blob as
ServerMessage::ClusterPreferences, but the desktop app does not auto-apply it; the user must click Pull from cluster to overwrite local state.
Conflict resolution
Whole-blob last-writer-wins. A second client clicking Save to cluster right after the first one wins because the daemon stamps a newer updated_at. There is no per-key merge; if you push, you push everything your client has under clusto-*.
Wire protocol
ClientMessage::GetClusterPreferences→ServerMessage::ClusterPreferences.ClientMessage::SetClusterPreferences { preferences }→ daemon persists, broadcasts to peers, and replies/broadcastsServerMessage::ClusterPreferences.PeerMessage::SyncClusterPreferences { preferences }- peer-to-peer replication of the blob (LWW onupdated_at).