Lesson 1 of 7 · HQ fundamentals

Install HQ on Mac or Windows

Download HQ, sign in, and pick where your HQ folder lives. HQ installs in the background, then HQ Desktop opens a short guided setup.

Download for macOS Windows Begin lesson

Written path: 8 steps

Before You Begin

A Mac or Windows PC with permission to install apps. HQ isn’t available for Linux yet.
A Google or Microsoft account to sign in with.
A Claude account for Claude Code, or a ChatGPT account for Codex. You don’t need either one installed yet. HQ helps you sign in during setup.

Step 1: Download HQ
Go to the HQ install page and click the download for your computer: Download for macOS on a Mac, or Download for Windows on a PC. Wait for it to finish.
Go toOpen this place
```
→ https://hqforwork.com/install
→ Select Download for macOS or Download for Windows
```
Expected
HQ.dmg (Mac) or the HQ setup .exe (Windows) is in your Downloads folder.
Note
On Windows, your browser may hold the HQ setup file because it isn’t commonly downloaded. In Edge, open the Downloads panel, click the three dots on the file, choose Keep, then Show more and Keep anyway. In Chrome, open the file’s menu and choose Keep. In Firefox, right-click the paused file in the Downloads panel and choose Allow Download.
Step 2: Open HQ
On a Mac, open HQ.dmg and drag HQ into your Applications folder, then open HQ from Applications. On Windows, run the HQ setup .exe from your Downloads folder. If Windows SmartScreen asks you to confirm, click More info, then Run anyway, and click Yes when Windows asks to make changes.
Go toOpen this place
```
→ Mac: drag HQ onto Applications, then launch HQ
→ Windows: run the HQ setup .exe
```
Expected
HQ opens full screen and says Everything you need. In one place.
Step 3: Sign in
Click Continue with Google or Continue with Microsoft. A browser window opens so you can sign in. Finish there and HQ picks up where you left off.
ChoosePick this in HQ
```
— Continue with Google
— or Continue with Microsoft
```
Expected
HQ shows It’s a folder and suggests where your HQ folder should live.
Note
Joining a team? Sign in with the email your invite went to, so your team’s company shows up.

Step 4: Choose where HQ lives

HQ keeps everything in one folder on your computer and keeps it in sync. The suggested spot works for most people, or click Choose… to pick your own. Then click Install here.

ChoosePick this in HQ

— Install here

Expected

HQ starts installing in the background. A small card in the corner shows its progress.

#          Q       :                 ,·     H     +  #                       +      .  H,               
 0 0·  .     H       :   H*        #  #. *   Q      ·+#            :*   +    Q        +   H ,          #
  H  :#       0         :   0      ,H      #    , /H    *          H, 0# H Q     Q #       0 0   0      
    / Q :   ,:+: 0, +    ·#   .   Q*  #   .+#, Q       //. *#+                   .  H   #.:   *     */ *
+ #     */ H* // / /        ,0       +0· , Q  .Q     +     Q   H     ·:#H  ,/      0Q ** H: +:        . 
  :    H H          0   +   H  +   0  /    +      ·  .+ *:        ##. H/.:  H+  /  /   H 0 Q/, / Q    0·
*   / 0/ #     H QH   *   #  Q·# /  Q·++Q  ·   :#:   .·  . ##   .  Q: #    / 0·/ ·0/   #  *H* ,  Q   , +
 :  ,.:H,/#   H  * .H  :  ·Q 0 HH     . */  #  :    ///: + +  :   # */:**Q, *     Q ·  /: ·# HH0,#  Q + 
*Q/H++0  */QQH :/  //:Q ++#,  ++  ·H:+Q /   0   .Q *,*     #  ++0  ·  .: +·0 ..:          # .Q Q :* ·

It's a folder

HQ lives on your machine as plain files. Your work, your rules, your team’s memory. Any AI sits on top of it.

HQ/

companies/A wall per client. One company’s context can never reach another’s.

personal/You. Your preferences and the rules you teach HQ, in every company.

repos/Your actual code. Nothing wrapped, nothing hidden.

workspace/Sessions, drafts, and handoffs. The memory between chats.

core/HQ’s own machinery. An update replaces this and never your work.

Pick where it lives. You can move it any time.

HQ~/HQChoose…

Install here

Back

Step 5: Watch the two short explainers
While HQ installs, two screens explain how it works: your folder stays on your computer while your team shares a company cloud, and one keyboard shortcut opens HQ from anywhere. Click Next on each, or Skip intro.
ChoosePick this in HQ
```
— Next
— or Skip intro
```
Expected
HQ shows Almost ready. while the install finishes, then HQ is ready.
Note
Install usually takes a couple of minutes on a Mac. Windows can take a bit longer while antivirus scans run.
Skip intro
Your folder is local. Your team is not.
Every machine syncs to the same company cloud. People and bots share one context.
company cloud
messagesagentssyncdeploysteamyousecretspermissions
syncSame on every machine
secretsInjected at run time
permissionsWho sees which folder
deploysAnything becomes a link
messagesPeople and bots, one thread
Next
Installing HQ in the backgroundStep 1 of 5 · Laying the groundwork
Back
Step 6: Start or join your company, if HQ asks
If you aren’t part of a company yet, HQ asks you to start one or join the company that invited you, then sign up free or request an enterprise demo. If you already belong to a company, HQ skips this screen.
Expected
HQ shows HQ is ready.
Note
Not ready to choose? You can also set up your team in the next part of setup.

Step 7: Open HQ Desktop

Key step

On the HQ is ready screen, leave Share anonymous usage data ticked or untick it, then click HQ Desktop. HQ never collects your prompts or files, and you can change this later in Settings.

ChoosePick this in HQ

— HQ Desktop

Expected

HQ Desktop opens to a full-window setup screen.

#          Q       :                 ,·     H     +  #                       +      .  H,               
 0 0·  .     H       :   H*        #  #. *   Q      ·+#            :*   +    Q        +   H ,          #
  H  :#       0         :   0      ,H      #    , /H    *          H, 0# H Q     Q #       0 0   0      
    / Q :   ,:+: 0, +    ·#   .   Q*  #   .+#, Q       //. *#+                   .  H   #.:   *     */ *
+ #     */ H* // / /        ,0       +0· , Q  .Q     +     Q   H     ·:#H  ,/      0Q ** H: +:        . 
  :    H H          0   +   H  +   0  /    +      ·  .+ *:        ##. H/.:  H+  /  /   H 0 Q/, / Q    0·
*   / 0/ #     H QH   *   #  Q·# /  Q·++Q  ·   :#:   .·  . ##   .  Q: #    / 0·/ ·0/   #  *H* ,  Q   , +
 :  ,.:H,/#   H  * .H  :  ·Q 0 HH     . */  #  :    ///: + +  :   # */:**Q, *     Q ·  /: ·# HH0,#  Q + 
*Q/H++0  */QQH :/  //:Q ++#,  ++  ·H:+Q /   0   .Q *,*     #  ++0  ·  .: +·0 ..:          # .Q Q :* ·

HQ is ready.

HQ lives in your menu bar now and keeps everything in sync.
Open HQ Desktop and your setup bot will walk you through the rest.

✓Installed and synced across your devices.

HQ DesktopUse HQ’s own appClaude CodeCodex

✓Share anonymous usage data·What’s collected·Enable HQ Anywhere

Step 8: Start the guided setup
HQ Desktop asks you to name your HQ assistant. This assistant finishes setting up HQ with you and stays to help afterwards. Lesson 2 walks through every screen.
Expected
You see Name your HQ assistant.

You’re done when

HQ is installed, HQ Desktop is open, and you’re on the Name your HQ assistant screen.

Hit a snag? Here’s the fix.

HQ won’t open

On a Mac, open HQ from your Applications folder, not from the disk image. HQ is signed and notarized by Apple, so macOS shouldn’t block it. On Windows, if SmartScreen or your antivirus stops the setup .exe, click More info, then Run anyway, or allow the app in your antivirus. If you still see a warning, reach out to support and we’ll fix it.

Sign-in didn’t finish

Finish signing in in the browser window that opened. If you still see an error, click Continue with Google or Continue with Microsoft again. If it says a sign-in port is busy, close any other sign-in windows and try again.

The install is taking a long time

The card in the corner shows what HQ is doing and how long it has been running, so you can see it’s still moving. On Windows, antivirus scans can slow it down. Leave the window open and let it finish.

It says no coding tool is signed in

You’ll see this during setup in HQ Desktop. Click Sign in with your Claude account (for Claude Code) or Sign in with your ChatGPT account (for Codex) and finish in your browser. HQ notices on its own when you’re done. Lesson 2 shows the screen.

Something else going on? The HQ knowledge base walks through the most common fixes, or reach out and we’ll help you get unstuck.