Cloud Sync

Overview

HQ Cloud Sync keeps your local HQ folder in sync with cloud storage (S3). Each cloud-backed company has its own vault, and you have a personal vault. Teammates in the same company sync from the same company vault; each membership’s sync mode (shared, all, or custom) sets which files it pulls.

Local HQ  ←→  hq-sync-runner  ←→  Company vaults + personal vault (S3)
              (run by HQ Desktop)

Setup

With HQ Desktop

Install HQ Desktop and sign in (see Getting Started). HQ Desktop runs sync in the background: it starts hq-sync-runner --watch, which watches your HQ folder and syncs changes.

With the CLI

npm install -g @indigoai-us/hq-cli

hq login

This opens your browser to sign in. Your tokens are stored at ~/.hq/cognito-tokens.json.

Then sync:

hq sync now --all

hq sync now pushes local changes, then pulls remote updates. --all covers every company you are a member of plus your personal vault. To make a local company cloud-backed, use hq cloud provision company <slug>.

Commands

Command	Description
`hq login`	Sign in to HQ
`hq sync now`	Push local changes, then pull remote updates (the same as Sync Now in HQ Desktop)
`hq sync push`	Push local files to the company vault
`hq sync pull`	Pull the files you have access to from the company vault
`hq sync status`	Show the local sync journal summary
`hq sync mode`	Set a membership’s sync mode (`shared`, `all`, or `custom`), or `--show` the current modes
`hq sync narrow`	Move a company membership from sync mode `all` to `shared` (dry run unless `--apply`)
`hq sync held`	Show uploads held because someone else was signed in on this computer
`hq sync release-held`	Confirm held files are yours and let sync upload them
`hq sync manifest`	Upload a file manifest for the sync reconciliation audit
`hq sync doctor --reconcile-conflicts`	Clean up legacy `.conflict-*` twin files (dry-run; add `--yes` to apply)
`hq cloud provision company <slug>`	Make a local company cloud-backed: provisions the vault entity if missing, updates `manifest.yaml`, and runs an initial sync
`hq access <path-or-query>`	One file missing or locked? Reports never-existed / not-synced / no-access, fetches it when you have access, otherwise asks the owner for a grant (see hq-share)

push, pull, and now take --company <slug>, --personal, or --all. Run hq sync <command> --help for every option, or see the CLI reference.

How Sync Works

File watcher — hq-sync-runner --watch watches your HQ directory
File hashes are compared against the sync journal
Changed files are uploaded to the matching vault: companies/{slug}/ goes to that company’s vault, and everything else goes to your personal vault
The journal is updated with new hashes. There is one journal per company, at ~/.hq/sync-journal.{slug}.json

Conflict Resolution

When the same file changed on both sides, sync picks a winner without leaving anything next to the live file:

If both copies carry a frontmatter version: number, the higher version wins.
Otherwise the newer modification time wins.
Identical bodies keep the local copy; a true tie keeps the cloud copy.

The losing copy is parked out of tree under .hq/conflict-backups/ (never synced), and the decision — winner, reason, and both versions — is recorded on the matching row in .hq-conflicts/index.json. The journal still tracks hash, size, timestamp, and sync direction for every file, and Git handles content-level conflicts for version-controlled files.

Cleaning up legacy conflict twins

Older versions of the engine wrote a sibling <file>.conflict-<timestamp>-<machine>.<ext> twin beside the live file. hq sync doctor --reconcile-conflicts walks your HQ root and prints a plan for every twin it finds; add --yes to apply it (use --hq-root <path> to point at a different HQ):

A twin replaces the live file only when its frontmatter version: is strictly higher than the live file’s. Otherwise the live file stays and the twin is parked.
Twins whose live file no longer exists are parked, never restored, and listed for manual review.
Symlinked or unreadable twins are skipped and listed for manual review.

Everything parked lands in .hq/conflict-backups/, so no content is destroyed. The command is local-only and needs no cloud sign-in.

What Syncs

Vault	What it holds
Company vault	`companies/{slug}/` for each cloud-backed company you belong to
Personal vault	Top-level folders and files such as `personal/`, `core/`, `.claude/`, and `AGENTS.md`, plus `companies/manifest.yaml` and any local (not cloud-backed) companies

These are not synced:

repos/ (use git) and .git/
workspace/, except workspace/threads/handoff.json and its active thread, workspace/agency/, and workspace/.session-logs/
node_modules/, build output such as dist/, build/, and .next/, and caches
Secrets: .env files, credentials.json, *.credentials.json, .mcp.json, .secrets/, and companies/{slug}/secrets/ and companies/{slug}/settings/
.claude/settings.json and .claude/settings.local.json, at any depth
Files over 50 MB
Paths in .hqignore

.hqignore and .hqinclude

Edit the .hqignore file in your HQ root (HQ ships one) to exclude more paths (gitignore syntax). Use !pattern to re-include something the defaults exclude. Sync does not read .gitignore. The older name .hqsyncignore still works when there is no .hqignore.

# Exclude large data files
companies/*/data/exports/*.csv

# Exclude temp files
personal/scratch/

To sync only what you list, create a .hqinclude file in your HQ root. When it exists, a path syncs only if it matches a pattern in .hqinclude. The default exclusions and .hqignore still apply on top.