Skip to content
Indigo HQ Docs

HQ desktop app

The HQ desktop app is one installer and sync app. On first launch it creates your HQ workspace and guides you through setup. After onboarding, the same app lives in the macOS menu bar or Windows system tray and keeps your local HQ directory synced with the cloud.

What it is

  • A Tauri 2 desktop app (small Rust backend + Svelte 5 UI), distributed for macOS and Windows.
  • One download, version, and updater stream for installation and ongoing sync.
  • A system-tray agent with per-workspace sync rows, real per-file progress, a Stop button, conflict resolution, a compact messages-and-notifications popover, full desktop messaging, share reactions, and Connect diagnostics.

Who uses it / when

Use the desktop app to install HQ and keep it synced in the background without running hq sync commands by hand. Power users who live in the terminal can keep using the hq CLI directly; both drive the same engine.

First-run onboarding

Download HQ from hqforwork.com/install, sign in, choose a workspace location, and select Install. The final HQ is ready screen offers Open in Claude Code and Open in Codex.

Selecting either tool completes onboarding, opens the workspace there, and hands control to the compact sync popover. There are no additional desktop onboarding screens to dismiss. If you prefer to open the workspace manually, select Finish.

How it works

The desktop app is a GUI over the engine, not its own sync implementation. It spawns the hq-sync-runner binary shipped by @indigoai-us/hq-cloud, reads the ndjson sync events that runner emits, and renders them as live progress in the menu bar or system tray. The actual bidirectional S3 transfer, journaling, and conflict detection all happen in the cloud engine.

Distinction: The HQ desktop app owns onboarding and the tray UI. The sync engine is @indigoai-us/hq-cloud, and the same engine is also invoked by hq sync from the CLI. The app does not contain its own sync logic.

The full desktop workspace

Select Open HQ from the compact menu-bar or system-tray window to open the complete desktop workspace. It brings Inbox, Messages, Meetings, Marketplace, Library, Files, company workspaces, projects, tasks, goals, and settings into one native window.

The desktop workspace keeps source context visible. Projects and tasks show their owner or creator when HQ can establish that identity, along with their company and source path. Knowledge files render Markdown directly, including tables, code, lists, quotes, links, and task lists.

Instant DM delivery

HQ Sync also receives direct messages — sent with hq dm or the /dm command — and surfaces them as native macOS notifications, with one-click “Copy prompt” and “Open details” actions and an inline reply. “Open details” opens the full two-way conversation thread — your messages and theirs, in order — not just the single notification, so a DM reads as a conversation rather than a one-off alert.

As of 0.3.0, DMs arrive near-instantly (p95 under 3 seconds, end-to-end) instead of waiting on a polling interval. HQ Sync subscribes to a per-user topic on an AWS IoT Core (MQTT-over-WebSockets) real-time fabric; the moment a DM is stored, a lightweight wake event is published to the recipient’s topic and the menubar fetches and shows it immediately.

Key properties:

  • Per-identity isolation — each client connects with short-lived, scoped credentials and can only subscribe to its own DM topic; cross-user topics are denied at the broker.
  • No DM is ever lost — the durable store is the source of truth and MQTT is only the wake signal. If the real-time connection is unavailable, delivery falls back to the existing periodic poll with no loss and no regression.
  • Nothing to configure — the real-time path is automatic for signed-in users; DM notifications can be turned off in HQ Sync settings.

Manage packages

HQ ships capabilities as packs (engineering, design, and more). From Settings → Packages → Manage…, HQ Sync opens a dedicated Packages window where you can browse, install, update, and uninstall packs without touching the terminal:

  • Installed packs show their version, an “update available” badge, and a warning if any of their links are broken — each with Update and Uninstall actions.
  • Available shows the curated pack catalog plus any registry packages you’re entitled to, each with an Install action.
  • Installs and updates stream live progress; uninstalls cleanly remove a pack’s wiring and archive it.

Like everything else in HQ Sync, the window is a GUI over the hq CLI — it wraps the hq packs commands (see hq-cli) so the CLI and the app share one implementation.

Messages and notifications

The compact window is a quick triage surface for messages, channel activity, shares, sync events, and updates. As of 0.10.35, the HQ menu-bar icon carries an unread-message badge, while the popover gives senders, conversation context, timestamps, and primary actions more breathing room. Repetitive automated activity is grouped instead of flooding the list. Select Open messages for the complete conversation workspace, or Open HQ for the desktop home.

The feed brings the main notification types into one view:

  • Direct messages you’ve received — click through to the full conversation thread and reply.
  • Channel activity that needs your attention — open the relevant conversation.
  • Files shared with you — click through to the share details.
  • New files synced to your drive — the files teammates added, attributed to whoever added them.
  • Product updates — open the updater directly instead of landing in an unrelated inbox.

Direct messages and shared files show their full history (the server retains them). New-file history fills in across sessions as your hq CLI updates to the version that reports them — within a session, the current sync’s new files always appear.

White-label branding (Enterprise)

If your company is on the Enterprise plan and has set up branding in the HQ Console, the desktop app wears it too: your company logo appears in the app (with a permanent “powered by HQ” mark beneath it), and your chosen accent color is applied across the app’s chrome in both light and dark appearance. Status colors keep their standard meanings.

Branding travels with your normal sync — no extra setup on the desktop — and is cached locally, so it still renders when you’re offline. If the company’s branding is removed or the plan changes, the app returns to the standard HQ appearance on the next sync.

Appearance and reading size

Open Settings → Appearance to tune the desktop without changing the meaning of any status color:

  • Theme — follow the system, or choose Light or Dark.
  • Window opacity — choose any value from 0% to 100%. 100% is fully solid; lower values reveal more of the native Liquid Glass or Mica material.
  • Interface size — adjust the app-wide reading size with the slider, or use Command + / Command - on macOS and Control + / Control - on Windows. Command 0 or Control 0 returns to 100%.

Appearance applies across the app and persists between launches. The desktop also respects the operating system’s Reduce Transparency and Reduce Motion accessibility settings.

On macOS, Settings → General → Show in Dock can add HQ to the Dock and app switcher. It is on by default; turn it off to keep HQ in the menu bar only.

Share reactions & messaging the sharer

When someone shares a file with you, the share isn’t a dead-end alert (as of 0.9.8):

  • React with an emoji — share details and the notification feed carry the same reaction bar DMs use. Reactions are scoped to the share, visible to the sharer and every recipient, and update in near-real-time over the same instant-delivery fabric DMs use.
  • The sharer hears about it — reacting to a share automatically sends the sharer a direct message, so a 👍 closes the loop without anyone composing anything.
  • Message the sharer — a one-click action opens a DM conversation with the person who shared the file, deep-linked from the share itself.
  • Share history lives in Messages — files a person shared with you appear inline in your DM thread with them as share cards, and conversation previews show “Shared a file,” so shares and messages read as one conversation.

Install & updates

The HQ desktop app ships through GitHub Releases as a signed, notarized macOS DMG (minimum macOS 13.0) and a Windows installer. It auto-updates via a published latest.json manifest — once installed, new versions are offered automatically.

Releases are cut from the unified hq-desktop-app repository. Installation and sync therefore always move forward on the same version and updater stream. The app version is visible in the desktop toolbar and update popover. Settings also shows the installed HQ Core version, release channel, automatic-update state, and a manual Check for updates action.