Sync: How It Works and How to Fix It

Illustrative · if HQ isn't running, nothing syncs

Sync is how the HQ folder on your laptop and your team's shared cloud copy stay matched. If a teammate adds a document, sync brings it to you. If you write one, sync carries it to them. This article explains the mental model, how to run sync, what a "conflict" really is, and how to fix the most common sync failures.

The mental model: your laptop ⇄ the cloud#

Picture a two-way bridge:

  Your laptop                    HQ Cloud
  companies/acme/   ⇄   Acme's encrypted vault

• Sync is bidirectional. It downloads teammates' changes and uploads yours, in one pass.
• It works per company. Each cloud-backed company (an isolated team workspace whose files are connected to an encrypted cloud vault) syncs against its own vault. Companies that were never made cloud-backed don't sync at all, and nothing crosses between companies.
• Two things run the same sync engine: the HQ app (which syncs automatically in the background) and the /hq-sync command you can type in a session. Same engine, two ways to trigger it.
• While a sync is running, the sync label in the top bar of the HQ window shows its progress. To see your sync status any time, click Core at the top of the window. It shows something like All synced and Last sync · 3m ago, or a warning such as Sync paused or Needs attention. To sync right away, right-click the HQ icon in your menu bar (Mac) or system tray (Windows) and choose Sync Now.
• When you create or join a company, HQ syncs it to your computer by itself. If that fails, an Added to banner with the company's name appears with a Sync now button. Click it to try again.
• After a sync that downloads files, HQ reindexes your folder, so new company skills show up for teammates without extra steps.
• Sync options are in Settings → Sync, including Auto-sync, Instant sync, and Sync on launch. To open Settings, click your picture at the bottom of the left rail and choose Settings, or press Cmd+, on a Mac (Ctrl+, on Windows).

If you're still deciding whether cloud is for you, start with HQ Cloud explained.

Running a sync yourself#

Type this in a Claude Code session inside your HQ folder:

/hq-sync

It checks that you're signed in, walks every cloud-backed company, syncs both directions, and prints a summary like:

Companies synced: 2
Files: 14 ↓ / 3 ↑
Conflicts: 0

That's it. If conflicts appear, keep reading.

Freeing disk space#

Sync keeps a backup history of your files, which grows over time. To see how much space it uses, or to move big files to HQ cloud and delete old backups, go to Settings → Storage. Everything's covered in Storage and Disk Space.

Conflicts: what they are and why they're safe#

A conflict happens when the same file was edited in two places between syncs. You changed it on your laptop while a teammate (or your other machine) changed it in the cloud. HQ can't know which version you want, so it refuses to guess.

Here's the important part: sync never deletes your work silently. When it detects a conflict, it keeps both versions on disk. Your local copy stays exactly where it was, and the cloud's version is saved right next to it as a .conflict-... file. Then HQ asks you to choose. (Even a discarded cloud version isn't truly gone. The cloud keeps version history.)

To work through pending conflicts:

/resolve-conflicts

It walks each conflicted file one at a time, shows you both versions and what differs, and asks what to do:

1. Keep local: your copy wins; the cloud version's sidecar file is removed.
2. Take cloud: the cloud copy replaces yours.
3. Merge: it opens both files side by side so you can combine them by hand.
4. Skip: leave both in place and decide later.

When you're done, run /hq-sync (or right-click the HQ icon in your menu bar or system tray and choose Sync Now) again so your resolved version reaches the cloud cleanly.

Troubleshooting#

"Sync just… never happens": HQ isn't running

HQ syncs in the background as long as the app is running, even with its window closed. If it was quit, or didn't start after a restart, nothing syncs and nothing tells you.

1. Look for the HQ icon in your menu bar (top-right on a Mac) or system tray (bottom-right on Windows). If it's there, HQ is running. Your problem is elsewhere, so keep reading.
2. If it's not there, open HQ from Applications (Mac) or the Start menu (Windows). HQ starts at login by default. If it didn't, turn on Settings → General → Launch at login.
3. Check Settings → Sync and make sure Auto-sync is on.
4. While you sort that out, /hq-sync in any session runs the same sync engine, so you're never blocked.

"Not signed in" errors

Sync needs to know who you are. If /hq-sync says you're not signed in or your session expired:

1. Check: /hq-whoami. It tells you who's signed in and when the session expires.
2. Fix: /hq-login. It silently refreshes if possible, and opens your browser to sign in if not.
3. Run /hq-sync again.

"My work isn't showing up on my second machine"

You finished a session (one conversation with HQ) and did a handoff (a saved summary that lets a future session pick up where you left off). But on your other machine, none of it's there. Check, in order:

1. Same account on both machines? Run /hq-whoami on each. Different logins mean different clouds.
2. Did both machines actually sync? Run /hq-sync on the machine where you did the work (to push), then on the second machine (to pull). If HQ wasn't running on either machine (see above), automatic sync never happened on that side.
3. Is the file in a place that syncs? Files inside cloud-backed companies sync to your team. Your workspace and handoff threads sync too, but through your own private personal scope, so they reach your other machines rather than your teammates. Raw session logs stay on the machine where they were created.

If work still isn't appearing after both machines sync cleanly, that's worth reporting: /hq-bug.

"I'm scared sync will overwrite or delete my files"

It won't. Sync's default behavior on any disagreement is keep local: your copy stays put and the other version is saved alongside it for you to review. Nothing is deleted silently, and every conflict is surfaced in /resolve-conflicts for you to decide. The worst a missed sync can do is leave you with out-of-date files until the next sync.

Common questions#

If you get stuck#

Nine times out of ten it's one of two things: HQ isn't running (open it, or use /hq-sync meanwhile) or you're not signed in (/hq-login). If neither fixes it, try the "I'm stuck" guide or file /hq-bug with what you saw.