Getting Started

02 / Guided course

Learn HQ in the order it is used.

7 lessons

Start with installation, then build toward a shared company, safe access, durable handoffs, and reusable workers. Each lesson includes the full video and a step-by-step field guide.

  1. Lesson 1

    Install HQ on macOS

    Download the HQ desktop app, create your local HQ workspace, open it in an AI coding tool, and begin the guided setup flow.

    5–8 minutes
  2. Lesson 2

    Set Up Your HQ Company and Team Workspace

    Complete the setup interview, create your company workspace, make it shareable with a team, and save the finished session for later recall.

    10–15 minutes, plus provisioning time
  3. Lesson 3

    Store and Share API Keys with HQ Secrets

    Submit a provider credential through HQ's secure form, choose who may use it, and verify access without putting the raw value in chat or documentation.

    About 5 minutes
  4. Lesson 4

    Deploy a Private HQ App

    Turn an approved idea into a small web app, restrict it to company members, and prove the access gate in a private browser session.

    About 3 minutes, plus build time
  5. Lesson 5

    Onboard a Team Member with /new-hire

    Invite a teammate, choose least-privilege role and resource access, prepare a starter package, and verify the recipient's first HQ session.

    8–10 minutes
  6. Lesson 6

    Resume, Hand Off, and Collaborate on a Project

    Scope a session to a company and project, capture an early brainstorm, save it with a handoff, and let a teammate resume the same work elsewhere.

    8–10 minutes, excluding sync latency
  7. Lesson 7

    Create, Train, and Share a Reusable HQ Worker

    Create a narrow company worker, inspect its durable files, enrich it with reusable design knowledge, and share it as living team infrastructure.

    10–15 minutes

Before you start

  • A MacBook Pro — 16 GB RAM minimum, 32 GB recommended. HQ runs natively on macOS.
  • One coding agent + plan — either Claude Code with Claude Max ($100/mo), or Codex with ChatGPT Pro ($200/mo).

Install HQ

01

Head to hqforwork.com/install and download the installer. Pick a folder for your HQ, create your account, and set up your first company. While you wait, the installer runs dependency installs in parallel and sets up the Sync app.

1Welcome
2Install
3Templates
4Prerequisites
5Sign In
6Workspace
7Personalize
8Verify
9HQ Sync
10Done

Set up HQ

Pick a folder, create your account, set up your first company. Dependencies install in parallel while you configure.

Get Started

Open the Sync app

02

Once installed, open the Sync app with the keyboard shortcut below. This keeps your local HQ in sync with the cloud — files, knowledge, and session state travel with you across devices.

+Shift+H
HQ
HQ~/Documents/HQ
Sync
Last syncednever
  • Personal personalLast sync · never
    PERSONAL
  • Acme CorpLast sync · never
    PENDING
  • IndigoLast sync · never
    PENDING
☼ Settings↪ Sign out

Open HQ in your AI tool

03

Open your HQ folder in Claude Code or Codex. Run /setup to finish initial configuration — it wires up commands, verifies dependencies, and prepares your workspace.

HQ / Acme

Setup complete

  • Slash commands verified
  • Workers loaded
  • Knowledge indexed
  • Workspace ready
Local HQ main | worktree
/setup
Auto modeOpus 4.8 · High

Open a new session

04

Start a fresh session in your AI tool. Each session is a clean context window — no accumulated noise from prior work.

Start work

05

Run /startwork [company-slug] to begin.

This resolves your company context, loads policies, surfaces available worker routes, and persists session metadata. It's how HQ knows what you're working on and what tools are available.

HQ / Acme

Session started

  • Company: Acme Corp
  • Policies: 4 company, 2 repo (1 hard)
  • Workers: 8 available
  • Active project: acme-dashboard — 3/7 stories done

Ready to work. Pick a story or describe what you need.

Local HQ main | worktree
/startwork acmeHelp me create a new skill
Auto modeOpus 4.8 · High

Create your first file

06

Create a knowledge file or skill — if you're not sure where to start, a knowledge file is a good default. This is where your team's context lives: decisions, architecture, specs, playbooks.

HQ / Acme

Created knowledge file

  • companies/acme/knowledge/engineering/api-patterns.md
  • Indexed in qmd collection

Knowledge files are available to every session automatically.

Local HQ main | worktree
create a knowledge file for our API patterns
Auto modeOpus 4.8 · High

Push to cloud

07

Sync your work using /hq-sync, or just tell your AI to sync. You can also click Sync in the app bar (top-right corner of the Sync app).

HQ
HQ~/Documents/HQ
Sync
Last syncedjust now
  • Personal personalLast sync · just now
    PERSONAL
  • Acme CorpLast sync · just now
    SYNCED
  • IndigoLast sync · just now
    SYNCED
☼ Settings↪ Sign out

Share with your team

08

Run /hq-share or tell your AI to share. This mints an encrypted, single-use link and opens a browser picker to grant your teammates access to the shared vault paths.

HQ / Acme

Share link created

  • Encrypted single-use link minted
  • Grants access to 3 vault paths
  • Link expires in 15 minutes

Send the link — your teammate picks what to accept, right in the browser.

Local HQ main | worktree
/hq-share companies/acme/knowledge
Auto modeOpus 4.8 · High

End with a handoff

09

Run /handoff when you're done.

Handoff commits your work, writes a thread file, and saves a small pointer so the next session picks up exactly where you left off. Index and learning updates run in the background. No context lost between sessions.

HQ / Acme

Handoff complete

  • Thread T-20260519 written
  • 3 files committed
  • Handoff pointer saved
  • Next session resumes automatically
Local HQ main | worktree
/handoff
Auto modeOpus 4.8 · High

Commands cheat sheet

10

Bookmark the Operator Cheat Sheet — every command, slash pattern, and worker shortcut on one page.

/startwork/handoff/hq-sync/hq-share/plan/run/learn/setup

Keep going