Skip to content

feat(sync): sync the lists you choose between Macs through a shared folder, and a Settings window - #21

Merged
kasvith merged 12 commits into
mainfrom
feat/sync-between-macs
Nov 6, 2026
Merged

kasvith merged 12 commits into
mainfrom
feat/sync-between-macs

Conversation

@kasvith

@kasvith kasvith commented Nov 6, 2026 •

Copy link
Copy Markdown
Owner

People asked for iCloud sync between their Macs, typically a work laptop by day and a home desktop in the evening, with each Mac choosing which lists are open.

CloudKit needs an iCloud entitlement, and an ad-hoc signed app can't carry one: that takes a paid developer account, Developer ID signing, a provisioning profile and notarisation. So Tic syncs through plain files in a folder that something else keeps in sync. That's iCloud Drive by default, or any Dropbox, Google Drive, OneDrive or Syncthing folder. It works with today's unsigned builds and curl installs. The design is in PLAN.md under "Sync between Macs".

How it works

  • One file per Mac. Each Mac writes only devices/<id>.json and reads the others', so a sync service never sees a write conflict.
  • A small CRDT (SyncMerge, pure and unit-tested like TaskOutline):
    • The newest stamp wins, field by field.
    • A list's task order and nesting are one value, so two reorders never interleave.
    • A delete always wins.
    • A stamp is max(now, highest seen + 1), so a slow clock can't undo an edit made after seeing a change.
  • Per list, opt-in. New lists stay on their Mac until their Sync switch is on.
    • The switch is in the list's ⋯ options, or in Settings › Sync, which lists every list.
    • The switch itself syncs: off on one Mac is off on all, and each Mac keeps its own copy.
    • Only synced lists are written to the folder.
    • Every Mac keeps recording all its lists locally, so switching one back on merges the copies field by field.
  • Scoped deletes. A list deleted while synced is deleted everywhere. One deleted while not synced only goes on that Mac; a trigger notes the switch at the moment of deletion.
  • Images travel as images/<sha256>.png, with the crop in the task's record.
    • A picture whose file hasn't arrived yet is taken on a later sync, not read as a removal.
    • Files are checked against their hash before use.
    • Files no Mac uses any more are cleared after a week.
  • Only content travels. Position, size, open or closed, rolled up, float and all-Spaces stay on each Mac. Lists made on another Mac arrive closed.
  • FolderSync runs a cycle at launch, 2 s after a synced edit, every 30 s, on wake, and right away when the Mac goes to sleep. It keeps a persisted device id and its own record beside the database.

UI

  • Settings window (⌘,):
    • General: Launch at Login, version, update checks (Daily, Weekly or Never), Check Now.
    • Sync: the switch, the folder, the other Macs with their latest changes, and a switch per list.
    • AI Agents: the MCP switch, with a client pop-up.
    • It replaces the menu's "AI Agents (MCP)…" and "Launch at Login" items and the MCP window.
  • On the note:
    • ⋯ › Sync, and Sync Now for a list that syncs.
    • The header's sync mark shows only while a sync touches the list, then fades. It stays orange while the folder can't be reached.

Sync is marked Experimental in Settings › Sync and on a list's Sync switch. Settings › Sync also says it's new and links to GitHub issues.

Site

  • Landing page: a sync feature marked new and experimental. Its demo shows two Macs holding the same list; ticking a task on either one appears on the other a moment later.
  • Six new guides.
    • For sync searches: "Can Stickies sync between two Macs?" and "How to sync a to-do list between two Macs". Facts about Apple's apps are checked against Apple's guides and the Stickies app itself.
    • For AI agents: "How to let Claude manage your to-do list on a Mac", "Give your coding agent a to-do list on your desktop", "What is an MCP to-do list?" and "How to connect ChatGPT and Codex to a to-do list on your Mac". The ChatGPT guide says plainly that ChatGPT on the web can't reach a local MCP server; this is checked against OpenAI's Codex docs.
  • Note replica matches today's app: a one-row header with ⋯, roll up, pin and close on hover, and a capsule rolled-up bar.
  • No more "no sync": the FAQ, llms.txt, comparison pages and the Stickies guide now say Tic syncs the lists you choose between Macs, with no phone app. The AI agents and Launch at Login steps point to Settings.
  • Site changes are in separate docs(site) commits, so the changelog skips them.

Test plan

  • swift build and swift test: 206 tests pass. pnpm build passes in site/.
  • SyncTests and FolderSyncTests: the merge rules, a two-database round trip, real files, an unreachable folder, a newer schema, and the device id surviving a lost state file.
  • SyncSimulationTests: two and three simulated Macs, each with its own database and copy of the folder, plus a pretend iCloud that can hold uploads back or deliver late. Covered:
    • arrival, tick cascade, and both Macs editing or reordering
    • delete vs later edit, and a list deleted while the other Mac adds to it
    • the lid closing before upload, and a clock 10 minutes slow
    • per-Mac window state, relaunch, and a half-downloaded file
  • SyncSharingTests:
    • choosing lists: a list never leaves the Mac until switched on; switched on later; off everywhere; back on merges; deleting an unsynced copy; switch off and delete at once; welcome notes stay put
    • images: arrival with crop, a late file, re-crop, replace, remove, unsynced pictures staying home, cleanup
  • SyncFuzzTests: 25 seeds of 40 random edits across three Macs, including sync switches and image changes. Every Mac must settle to the same synced lists, deletes stay deleted, nothing is lost, outlines stay valid, pictures match their hash, and a second sync writes nothing. A 400-seed run found the switch-off-then-delete bug, now fixed and pinned by its own test.
  • The v6 migration applied to a real database (7 lists, none synced).
  • Manual: Settings tabs; ⋯ › Sync and Sync Now on a list; the sync mark appearing during a sync.
  • Manual, with two Macs when available.

…ttings window

People asked for iCloud sync between their Macs, typically a work laptop
by day and a home desktop in the evening. CloudKit needs an iCloud
entitlement that Tic's ad-hoc signed builds can't carry, so Tic syncs
through plain files in a folder something else keeps in sync: iCloud
Drive by default, or any Dropbox, Google Drive, OneDrive or Syncthing
folder.

- Each Mac writes only devices/<id>.json and reads the others', so a
  sync service never sees a conflict. The merge (SyncMerge, pure) is a
  state-based CRDT: the newest stamp wins per field, a list's order and
  nesting are one value, a delete always wins, and stamps never fall
  behind what a Mac has seen, so a slow clock can't undo a later edit.
- Only content travels. Where a list sits, and whether it's open,
  rolled up or floating, stay on each Mac. Lists made on another Mac
  arrive closed.
- FolderSync syncs at launch, 2 s after an edit, every 30 s, on wake,
  and right away when the Mac goes to sleep. Each Mac keeps a persisted
  device id and its own snapshot beside the database. Images don't sync
  yet.
- A Settings window (Cmd-,) with General (Launch at Login, version,
  update checks daily, weekly or never, Check Now), Sync (the switch,
  the folder, the other Macs and when each last changed) and AI Agents
  (the MCP setup, with a client pop-up). It replaces the menu's
  "AI Agents (MCP)…" and "Launch at Login" items and the MCP window.
- Tests cover the merge rules, a two-database round trip, and a
  simulation of two and three Macs, each with its own copy of the
  folder and a pretend iCloud that can hold uploads back, plus a
  randomized run that checks every Mac settles to the same lists.
@bolt-new-by-stackblitz

Copy link
Copy Markdown

Review PR in StackBlitz Codeflow Run & review this pull request in StackBlitz Codeflow.

Sync is now per list and opt-in: new lists stay on their Mac until
their Sync switch is on (in the list's ⋯ options, or Settings › Sync,
which lists every list). Images in synced lists travel too.

- The switch is itself synced: turning it off on one Mac turns it off
  on all, and each keeps its own copy. Only synced lists are written to
  the sync folder. Every Mac keeps recording all its lists locally, so
  switching a list back on merges the copies field by field.
- A list deleted while synced is deleted everywhere; one deleted while
  not synced only on that Mac. A trigger notes the switch at the moment
  of deletion: a switch-off followed straight away by a delete wasn't
  recorded yet and deleted the list everywhere (the randomized run
  found this).
- Images travel as images/<sha256>.png, named by a new hash column,
  with the crop in the task's record. A picture whose file hasn't
  arrived yet is taken on a later sync rather than read as a removal,
  files are checked against their hash, and unused ones are cleared
  after a week. A replaced image refreshes its thumbnail on the other
  Mac even when the crop is unchanged.
- The note's sync mark shows only while a sync touches the list, and
  stays orange while the folder can't be reached. The ⋯ options have
  Sync and Sync Now.
- Tests: choosing lists (never leaves the Mac, on later, off
  everywhere, back on merges, scoped deletes, welcome notes stay put)
  and images (arrival, late file, crop, replace, remove, cleanup), and
  the randomized run now also switches lists and changes images.
The FAQ, llms.txt, the comparison pages and the Stickies guide said Tic
had no sync. They now say it syncs the lists you choose between Macs,
through iCloud Drive or another shared folder, with no phone app. The
AI agents and Launch at Login steps point to Settings, and the menu in
the desktop mockup shows Settings… instead of Launch at Login.
@kasvith kasvith changed the title feat(sync): sync lists between Macs through a shared folder, and a Settings window feat(sync): sync the lists you choose between Macs through a shared folder, and a Settings window Nov 6, 2026
Glass, Hide completed, Move completed to bottom and Sync now carry SF Symbols, like the action rows below them (Rename…, New List).
It shared the sync arrows with the Sync switch above it; it now uses the refresh arrow.
It's an action, not a setting: it now sits after New List and Clean Up instead of next to the Sync switch.
Each switch sat right after its own label, and symbols of different widths pushed the titles out of line, so the rows zigzagged and Move completed to bottom was cut off. Icons now sit in a fixed-width column shared by switches and actions, switches are pinned to the right edge, and the popover is 50pt wider.
With sync off in Settings the switch was greyed out under a link to Settings. It's now left out until sync is turned on, like Sync Now, which shows only for a list that syncs.
Settings › Sync and a list's Sync switch carry an Experimental tag, and Settings explains that sync is new, with a Report a Problem link to GitHub issues.
… look like today's

- A sync feature on the landing page, marked new and experimental: two
  Macs with the same list, where ticking a task on either one shows up
  on the other a moment later.
- Two guides for people searching for sync: "Can Stickies sync between
  two Macs?" (no; File › Export All to Notes, and Tic) and "How to sync
  a to-do list between two Macs" (Reminders and Notes through iCloud,
  what to do when the work Mac isn't on your iCloud, and Tic). Facts
  about Apple's apps are checked against Apple's guides and the Stickies
  app itself.
- The note replica now matches the app: one header row with ⋯, roll up,
  pin and close appearing on hover, and the rolled-up bar as a slim
  capsule. The options card in the finished-tasks section has the new
  icons.
- The FAQ and llms.txt say sync is experimental.
It pointed at the AI agents section; that section keeps its own New label.
- "How to let Claude manage your to-do list on a Mac": Claude Desktop's
  config file and Claude Code's mcp add command.
- "Give your coding agent a to-do list on your desktop": setup for
  Cursor, VS Code, Codex, Gemini CLI, Zed and Claude Code, a line for
  AGENTS.md or CLAUDE.md so the agent keeps its plan in Tic, and a table
  of the tools it can use.
- "What is an MCP to-do list?": how MCP works, what an assistant can do
  with your lists, what stays private, and setup.
- "How to connect ChatGPT and Codex to a to-do list on your Mac": one
  config.toml entry covers the Codex CLI, the IDE extension and the
  ChatGPT desktop app; ChatGPT on the web can't reach a server on your
  Mac. Checked against OpenAI's Codex docs.

The FAQ's AI agents answer links to the Claude guide.
@kasvith
kasvith merged commit 148998a into main Nov 6, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant