By name: hq-cowork-sync description: Run bidirectional HQ Sync from Cowork. allowed-tools: mcp__hq__hq_sync, mcp__hq__hq_whoami
/hq-cowork-sync — Sync HQ from a sandboxed agent
Runs the same sync engine the AppBar HQ Sync menubar app uses, but from inside a sandboxed Claude Code plugin host (Cowork, in particular). Walks every cloud-backed company in your local HQ, syncs in both directions against the vault, and writes conflict mirror files when divergence is detected.
Args: $ARGUMENTS — optional flags. Accepted shapes (parse free-text):
--company <slug>→ scope to one company--personal→ sync only the caller's personal vault--on-conflict overwrite|keep|abort→ conflict strategy (defaultkeep)--message "<msg>"→ optional journal message attached to push leg
Without args, syncs every membership + personal vault with --on-conflict keep.
When to use this instead of /hq-sync
- You're in Cowork or another sandboxed plugin host. The sandbox can't see
~/.hq/cognito-tokens.jsonandhqisn't on PATH inside it, so the regular/hq-syncskill (which spawnsnpx ... hq-sync-runner) cannot run. - You want native MCP tool-call ergonomics — observable in the host's tool log, not just shell output.
In a regular Claude Code session running on the host directly, prefer the
unprefixed /hq-sync skill — same engine, fewer hops.
What you do
Step 1 — Confirm the host MCP is wired
Before the first sync of a session, call mcp__hq__hq_whoami. If it returns
your identity + session expiry, the host MCP is live and authenticated. If
it errors with "not signed in" or "tokens expired", tell the user to run
hq login on the host machine (the sandboxed agent cannot do this itself
— hq login opens a browser on the host).
Step 2 — Call the sync tool
Parse $ARGUMENTS into the hq_sync tool's input schema:
| Arg pattern | Tool input |
|---|---|
--company <slug> |
{ "company": "<slug>" } |
--personal |
{ "personal": true } |
| (neither) | {} — server defaults to --all |
--on-conflict <strategy> |
{ "onConflict": "<strategy>" } |
--message "<msg>" |
{ "message": "<msg>" } |
Call mcp__hq__hq_sync with the assembled input. Sync output can be chunky
(per-company push + pull legs) — surface a terse summary, not the full log,
unless the user asked for verbose detail.
Step 3 — Report
Quiet by default. Surface:
- Companies synced (count + names)
- Conflicts written (count + the path to
<hqRoot>/.hq-conflicts/index.jsonif any — the user can run/resolve-conflictsnext) - Errors from any individual company leg (don't swallow them)
If conflicts were written, mention /resolve-conflicts as the next step.
Why this skill exists
The unprefixed /hq-sync skill resolves HQ root via four config tiers and
then execs the cloud-runner binary directly with the host's Cognito
session. None of that works from Cowork's sandbox, where ~/.hq is not
mounted and the host's Node binary isn't reachable. The
hq-pack-cowork MCP server fixes that by running on the host (with full
auth + binaries) and exposing hq_sync as a tool call the sandboxed agent
can make. This skill is the thin in-session adapter for that tool.