Installing HQ on macOS

What "running" looks like · the HQ icon stays in your menu bar after install

What you're installing#

HQ is one app. It installs your HQ folder (where all your HQ work lives), keeps it in sync, and gives you a desktop window for messages, projects, and setup. There's no separate installer and no separate sync app.

You do the hands-on work in an AI coding tool, Claude Code or Codex. Setup walks you through signing in to one, so you don't need either ready before you start.

What you need#

• A Mac running macOS 13 (Ventura) or later, with an internet connection.
• A Google or Microsoft account to sign in with.
• An account for the AI tool you'll use: a Claude account for Claude Code, or a ChatGPT account for Codex. You can decide which one later.

You don't need to install anything else by hand. HQ installs the supporting tools it needs, and it doesn't ask for your Mac password.

Step 1: Download HQ#

1. Go to hqforwork.com/install in your browser.
2. Click Download for macOS. A file called HQ.dmg lands in your Downloads folder.

Step 2: Move HQ into Applications and open it#

1. Open HQ.dmg.
2. Drag HQ onto the Applications folder.
3. Open your Applications folder and double-click HQ.

HQ is signed and notarized by Apple. If macOS asks whether you're sure you want to open an app downloaded from the internet, click Open.

Step 3: Sign in#

The installer fills the whole window. Click Continue with Google or Continue with Microsoft. A browser window opens. Finish signing in there, and HQ carries on by itself. If you're coming back to HQ and are still signed in, it may skip this screen.

If you were invited to a team, sign in with the email address the invite went to, so your team's company shows up automatically.

Step 4: Choose where HQ lives#

The next screen says It's a folder. HQ lives in one folder on your Mac. Keep the suggested location (a folder called hq in your home folder) unless you have a reason to put it somewhere else, or pick a different spot.

If you already have an HQ folder, you can pick it here and HQ will use it. HQ won't install into a folder that already has other files in it.

Click Install here.

Step 5: Let HQ get ready#

HQ installs in the background while two short screens explain how it works: your company's cloud, and the one keyboard shortcut that opens the HQ desktop view from anywhere on your Mac (Option-Shift-O). Click Next to move through them, or Skip intro. Leave the app open.

If you don't belong to a company in HQ yet, HQ asks whether you want to start one or join one, and which plan you want. If you're already a member, HQ skips this.

Step 6: Open HQ Desktop#

When you see HQ is ready., you can leave Share anonymous usage data checked or uncheck it. HQ works the same either way, and you can change it later in Settings.

Click the big HQ Desktop card. If you'd rather work in Claude Code or Codex, use the buttons under it instead.

Step 7: Guided setup#

HQ Desktop opens a short guided setup. It takes a few minutes:

1. Name your HQ assistant. HQ suggests a name. You can change it. Names can include numbers but must start with a letter. On a new computer, your existing assistant's name is already filled in.
2. Your team. "Who do you work with?" Join the company that invited you, Start a company, or pick Just me.
3. Your coding tools. Sign in to Claude Code or Codex. Sign in opens your browser. HQ notices when you're done on its own and shows Ready. If a tool isn't on your Mac yet, click Install Claude Code (or Install Codex) and HQ installs it for you. If you have the Claude or ChatGPT desktop app but haven't set up its coding tool yet, you'll see Open Claude (or Open ChatGPT): open it, use its coding tool once, then come back. One tool is enough. You can't skip this step.
4. Bring in your context. Click Bring it in and HQ reads the tools on this Mac (code repos and past Claude Code, Codex, or Grok sessions) so your assistant knows your companies, projects, and people. It reads only this Mac, and nothing leaves it. Or click Skip for now.
5. Note taker and Project management. These only show up when you're setting up with a company. Connect Fireflies, Otter, or Read.ai, and Linear, or click Next to skip.
6. Done. You see a summary. Click Talk to, followed by your assistant's name, to start chatting.

Your assistant picks up the rest of setup in chat and won't ask you things you already answered. After the context step you'll also see Continue in chat if you'd rather finish there, and Finish with defaults, which jumps to the Done screen and skips the optional screens you haven't done. To invite teammates later, just ask your assistant. What setup covers is explained in first-30-minutes.md.

For more on each tool, see Using HQ with Claude Code or Using HQ with Codex.

Already use Claude Code or Codex? You can run setup there instead. Open your HQ folder in that tool and type /setup, then press Return.

Confirm everything worked#

You're set when all three of these are true:

1. Guided setup ends on the Done screen and your assistant's chat is open.
2. Your HQ folder exists, with folders like core, companies, and personal inside it.
3. The HQ icon is in your menu bar, the row of icons at the top-right of your screen near the clock. To check sync, click Core at the top of the HQ window. It shows something like All synced and Last sync · 3m ago.

Common questions#

If you get stuck#

Start with Fixing a Failed Install. If your install finished but something isn't working, see im-stuck.md or the Sync Guide. Still stuck? Report it with /hq-bug. It packages the details for the team automatically.