Rolling HQ Out to Your Team: The Champion's Guide

One person sets it up, everyone gets smarter

You're the Champion: the one who saw HQ work and now wants your whole team on it. This guide is the sequence that works, get yourself solid first, create the shared workspace, bring people in one at a time, and let shared knowledge start compounding.

First, untangle three commands people always confuse#

New teams mix up /setup, /onboard, and /accept. Here's the decision tree:

What are you doing?
│
├─ Setting up HQ itself on your computer (first time ever)
│    → /setup        (run once per person, per machine)
│
├─ Dealing with a company (a shared team workspace)?
│    ├─ Creating one, or joining one, it asks which
│    │    → /onboard
│    └─ You got an invite link and just want in
│         → /accept <token>     (the shortcut for joining)

In short: /setup = your HQ (once). /onboard = a company (create or join). /accept = the fast lane for joining via invite link. A company in HQ is an isolated workspace for one business or team, its knowledge, files, and credentials never mix with any other company's.

Step 1. Get yourself set up first#

Don't invite anyone until HQ works for you. In the HQ app, a short guided setup opens on its own the first time you open HQ Desktop: you name your HQ assistant, pick your team, connect a coding tool, and bring in your context, one screen at a time. If you work in Claude Code or Codex instead, run the one-time setup there:

/setup

Either way, you get identity questions, folder scaffolding, and an orientation. Details are in Your first 30 minutes. On the Your team screen ("Who do you work with?"), pick Start a company and HQ sets the company up for you. Then ask your HQ assistant to invite your first teammates (Steps 2 and 3 below). Pick Just me only if you're trying HQ on your own for now. Then get one real piece of work done (Your first win). A Champion who can demo a personal win recruits a team far faster than one pointing at documentation.

Also sign in to HQ Cloud, since everything team-related rides on it:

/hq-login

Step 2. Create the company#

You have two paths:

• /onboard and choose create. It asks for your name, your email, the company's display name, and a short URL-safe identifier called a slug (like acme-corp). It then creates the company in the cloud, provisions its encrypted vault (the company's cloud file storage), and makes you the owner.
• /newcompany if you want the fuller treatment, it scaffolds the company folder locally and offers a business-discovery interview, seeded knowledge, and integrations. If you go this route, finish by making the company cloud-backed (connected to a vault so it syncs to your team):

/designate-team acme-corp

Rule of thumb: /onboard to get a shared workspace fast; /newcompany when you want HQ pre-loaded with context about the business.

Step 3. Invite your teammates#

You have a few ways to invite someone:

• Ask your HQ assistant. It asks for the person's email and whether they're a member or an admin, confirms, sends the invite, and tells you what they'll see.
• /new-hire in Claude Code or Codex walks you through inviting a person, giving them the right access, and checking it worked.
• The company page in the HQ app. Click Invite in the company's Team panel. It opens the HQ console at Team → Invites.
• The HQ console at hq.computer: go to Team and click Invite teammate.

However you send it, tell the person to check their spam folder if the email doesn't show up in a few minutes.

To do it from the command line, generate an invite for each person:

hq members invite teammate@yourco.com

By default this emails the claim link (a magic link of the form hq://accept/<token>) straight to that person, so you usually don't need to send anything yourself. If you'd rather deliver it manually, add --no-send-email and the command prints the link for you to pass along. The full form is hq members invite <email> --company <slug> --role <admin|member>.

What your teammate does (send them this, verbatim):

1. Install HQ and sign in with the email address the invite went to (Installing on macOS / Windows). In the guided setup, the Your team screen shows the company that invited them, marked Invited you. They pick it to join, and the company syncs to their computer by itself. They can also accept a company invite later from the Notifications bell in the top bar. If that sync fails, an Added to banner with the company's name appears in the HQ window with a Sync now button.
2. Working in Claude Code or Codex without the app? Run /setup, then sign in with /hq-login.
3. If they got an invite link instead, redeem it, either the shortcut:

   /accept hq://accept/<token>

or /onboard and choose join, pasting the token when asked. Both end the same place: they're a member, and their first sync pulls the company's shared files down to their machine.

Invites are tied to the invited person's identity, a link meant for one teammate can't be redeemed by someone else, and expired invites simply fail safely (generate a new one).

Step 4. Set roles#

Every member has a role. As owner, you adjust them with:

/promote <person> <owner|admin|member|guest>

Practical defaults: one or two owners, admins for whoever helps run the rollout, member for everyone else, guest for contractors or clients who should see only one corner (for example /promote psn_contractor guest --paths docs/). Only admins and owners can change roles.

Step 5. Let knowledge and skills flow#

This is where the team payoff starts. When you connect a company to the cloud with /designate-team, every member gets read and write access to four shared folders: knowledge/, projects/, policies/, and skills/. Anything saved there, like knowledge documents, skills (reusable instruction files that teach HQ a workflow), and project plans, syncs through the vault to every member automatically. Other folders stay private until you share them. For the full picture of who can see what, see Permissions in HQ.

If your company was connected to the cloud before this default existed, members may have no shared access yet. An owner can set it up, or change which folders members can see, with /team-access. Write a great process doc once; the whole team's HQ knows it by their next sync.

Two habits to seed early:

• Capture learnings into company scope. When someone figures something out, /learn routes it into shared knowledge instead of their private notes, see Teaching HQ.
• Answer "where did my skill save?" If a skill should be shared, it belongs under the company's folder (companies/<slug>/...), not in personal/, the personal/ folder is your private overlay and never syncs to teammates. Location determines audience.

For sharing individual files or finished artifacts (rather than living knowledge), see Sharing your work.

Your first-week rollout checklist#

1. ☐ Day 1: You run /setup, /hq-login, and ship one real personal win.
2. ☐ Day 1: Create the company (/onboard create, or /newcompany + /designate-team <slug>).
3. ☐ Day 2: Invite 2–3 friendly early adopters, not the whole team yet. Confirm each one's first sync pulled files down.
4. ☐ Day 2: Set roles with /promote; check that /hq-whoami and /hq-sync work on every machine.
5. ☐ Day 3: Seed the company with 3–5 genuinely useful knowledge docs (how you deploy, who your customers are, team glossary).
6. ☐ Day 3: Optional but high-impact, turn on meeting notes and signals so action items start capturing themselves.
7. ☐ Day 4: Have each early adopter ship their own first win and /dm it to the group.
8. ☐ Day 5: Invite the rest of the team; the early adopters are now your support crew.
9. ☐ Ongoing: watch for teammates saving shared things into personal/, the number-one silent rollout leak.

Common questions#

If you get stuck#

The most common rollout snags are sync-shaped: a teammate whose HQ app isn't running or who isn't signed in, both covered in the sync guide. For anything else, /hq-bug sends a report straight to the HQ team.