Your First 30 Minutes: What Setup Does

Illustrative · the one-time setup interview, about 20 minutes

The one thing to know before you start#

Almost nothing in setup is mandatory. The one step you can't skip is connecting a coding tool (Claude Code or Codex), because your HQ assistant runs on it. Everything else can be skipped and setup still completes. Say "skip" to anything else, anytime. The social questions are optional, and you can add everything later.

Setup is the one-time conversation that turns a freshly installed HQ folder into your HQ. There are two ways to start it:

• In the HQ app (most people). After install, click the HQ Desktop card on the HQ is ready. screen. HQ Desktop opens a short guided setup of up to seven screens:

1. Name your HQ assistant.
2. Your team ("Who do you work with?"): join the company that invited you, Start a company, or Just me.
3. Your coding tools: sign in to Claude Code or Codex. One is enough, and this is the step that can't be skipped. If a tool isn't installed yet, Install Claude Code (or Install Codex) installs it for you.
4. Bring in your context: click Bring it in so your assistant learns your companies, projects, and people from this computer. It reads only this computer, and nothing leaves it. Or click Skip for now.
5. Note taker: connect Fireflies, Otter, or Read.ai.
6. Project management: connect Linear.
7. Done: a summary and a Talk to button with your assistant's name.

Screens 5 and 6 only show up when you're setting up with a company, and you can click Next to skip them. From the context screen on, Continue in chat and Finish with defaults let you finish early. Your assistant then picks up the rest of setup in chat, starting at the first step you haven't done, without re-asking what you already answered. See Installing HQ on macOS or Installing HQ on Windows.

• In Claude Code or Codex directly. If you already use one of them, open your HQ folder in it and type:

/setup

Both run the same setup. The rest of this page covers what it does, phase by phase.

One quick disambiguation, because these three commands (the short instructions you type into Claude Code or Codex) get confused constantly: /setup = your HQ, run once. /onboard = create or join a company (an isolated workspace for one business or team). /accept = redeem an invite link someone sent you. If you were invited to a team, you still run setup first.

Phase 1: Health check and self-repair#

Setup first checks the record the HQ app left behind during install, a list of every install step, including any that failed. If something didn't land (a tool didn't download, the search index didn't build), setup explains what's missing in one sentence, fixes it, and checks the fix before moving on.

This is why "the install showed an error" is almost never a reinstall situation. Setup repairs it.

What it feels like: a short checklist scrolling by, with the occasional "want me to install this?" question.

Phase 2: Your team#

You already signed in to HQ with Google or Microsoft when you installed the app. Setup just confirms you're signed in to HQ Cloud, and if you aren't, opens a browser window so you can. It never blocks setup on this. Signing in is what turns on team sync (keeping your HQ current across machines and teammates), shared companies, and publishing your work behind a link.

If a teammate invited you, your team's company appears automatically as long as you signed in with the email address the invite went to. If you were sent an invite link instead, /accept with the link redeems it.

In the HQ app, guided setup asks "Who do you work with?" You can join the company that invited you, Start a company, or pick Just me. To invite teammates, ask your assistant. It asks for each person's email and whether they're a member or an admin, confirms, then sends the invite. Tell them to check their spam folder if it doesn't arrive in a few minutes. A new or joined company syncs to your computer by itself. If a company invite arrives later, accept it from the Notifications bell in the top bar of the HQ app.

Phase 3: Five questions about you#

Setup asks five questions, one at a time:

1. Your name.
2. What you do.
3. Your goals for HQ: what you want AI help with.
4. Your biggest pain points: what's slow, repetitive, or keeps slipping.
5. Your systems of record: where your work's truth lives (CRM, spreadsheets, email, a database, Slack…), and whether each has a credential you could connect later. You're never asked for a password or key here, only whether one exists.

These are worth answering well, and here's why: your answers become the standing context every future work session (one sitting of work with the AI) starts with. Name a real pain point, like "I lose two hours every Monday rebuilding the pipeline report," and everything downstream gets sharper. Setup's suggestions target that exact task, and future sessions attack it without being re-briefed. Vague answers ("be more productive") get you vague help. Two minutes of honesty here pays off for months.

Setup may also offer to look at your public profiles (LinkedIn, X, a personal site) to learn your voice, and (if you've used Claude Code before HQ) offer to import your existing skills, plans, and projects with /import-context (the old name, /import-claude, still works). Both optional, both skippable.

In the HQ app, your assistant can also connect the apps you use, one at a time, with your okay for each. After the first one works, it says something like "Great, Fireflies is connected" and links to your integrations page on hq.computer, where you can see everything that's connected. You can ask it, or any other AI in HQ, to connect another one later.

Phase 4: Your HQ folder takes shape#

Setup now scaffolds your workspace. No action needed from you. But it's worth knowing what exists when it's done:

• personal/: your private overlay. It holds your profile, preferences, and any skills (packaged, reusable workflows) or notes that belong to you rather than to a company. Inside it, personal/knowledge/ holds your knowledge base (the searchable notes HQ consults so it never has to re-ask): your profile, your systems-of-record list, and your voice notes.
• repos/: the single home for any code or content repositories you bring in later, split into public/ and private/.
• Profile files that HQ reads at the start of every session so it always knows who it's working for and what to prioritize.

Phase 5: The 60-second orientation#

Before finishing, setup gives you the HQ mental model in a screenful: sessions are disposable and context is precious (start with /startwork, do one focused thing, end with /handoff, the command that saves your state for next time); everything lives in one of three homes (personal/, companies/, repos/); knowledge compounds; and slash commands are how you drive. It also points you at /tutorial, a set of hands-on lessons you can take anytime. Deeper dive: mental-model.md.

Your assistant in the HQ app keeps this in plain words and doesn't ask you to type commands. The habit it teaches is simple: when you finish working in Claude Code or Codex, ask it to wrap up the session, so the next one picks up where you left off.

Phase 6: "Dream big," then a concrete launch plan#

Setup closes with two things:

1. Two or three tailored scenarios built from your answers: "you said X eats your time; here's the HQ capability that attacks it," so you can see the destination, not just the tooling.
2. A short interview about what you need first, ending in a personal launch plan: a list of exact commands to run next, each with a one-line reason tied to your goals. This plan is saved to personal/knowledge/getting-started-next-steps.md, so you can close everything and find it again tomorrow.

Setup also publishes a small private welcome page, your profile, your setup summary, and your launch plan as copy-paste blocks, and gives you the link.

In the HQ app, your assistant then offers to build you a bot of your own. If you started a company during setup, it may also offer to live in Slack so your team can ask it things there. That needs the Workforce plan: $500 a month for the company, plus $100 a month for the bot in Slack. The bot tells you the price and asks before setting anything up. You can also ask your assistant to do it later.

What to do next#

Close the setup session (fresh sessions are an HQ habit, and a good one), open a new one, and go get a real result on the board. That's the single most important move after setup. Half of new users stall right here, and the cure is shipping one small, real thing.

Go to your-first-win.md. It gives you three copy-paste-ready first projects, with exact commands, what HQ will ask, and what "done" looks like.

Common questions#

If you get stuck#

If setup halts on a broken dependency, just tell it "skip" and keep going. You can repair later by running setup again (it only fixes what's missing; it won't clobber your answers). For anything weirder, see im-stuck.md or file it with /hq-bug.