Using HQ with Claude Code

HQ isn't tied to one AI assistant. The HQ desktop app can run your setup and your day-to-day work through Claude Code or Codex. You only need one. This guide covers the Claude Code path. For Codex, see use-hq-with-codex.md.

What you need#

• The HQ desktop app, installed on your computer. If you haven't installed it yet, start with Installing HQ on macOS or Installing HQ on Windows and come back here at the "HQ is ready" screen.
• A Claude account. Claude Code signs in with your Claude account.
• The Claude desktop app (recommended). Claude Code runs inside it, in the Code tab. You can get it at claude.ai/download. If you'd rather use the command-line version, see "Using the Claude Code command line instead" below.

Step 1: Connect Claude Code to HQ#

You can do this during setup or at any time afterward.

During setup. When you first open HQ Desktop, it starts a full-window guided setup. One of its steps is Your coding tools. Click to sign in to Claude Code, and finish signing in in your browser. Your password never comes to HQ, and HQ notices on its own when you're done. You only need one coding tool, so Claude Code alone is enough. If it's already signed in, there's nothing to do here.

Afterward, from Settings. Settings isn't in the top bar, so it's easy to miss. To open it, click your picture at the bottom of the left rail and choose Settings, or press Cmd+, (Command and comma). Then click AI tools in the Settings sidebar. You'll see Claude Code, Codex, and Grok, each with a status:

Step 2: Run setup#

Setup is the one-time walkthrough that turns your new HQ folder into your HQ. It's covered in detail in first-30-minutes.md. You can run it in HQ Desktop or in Claude Code.

In HQ Desktop (the default). HQ Desktop opens a full-window guided setup. It goes step by step:

1. Name your HQ assistant.
2. Your team.
3. Your coding tools. Sign in to Claude Code or Codex in your browser. HQ notices when you're done. One is enough. This is the one screen you can't skip. If Claude Code isn't installed yet, click Install Claude Code. If you have the Claude app but haven't used its Code tab yet, click Open Claude, use the Code tab once, then come back.
4. Bring in your context.
5. Note taker. This step only shows up if you have a company.
6. Project management. This step only shows up if you have a company.
7. Done. Click Talk to <name>, where <name> is the name you gave your assistant. Your assistant finishes setup with you in chat.

In Claude Code. At the end of install, the HQ is ready. screen shows a big HQ Desktop card. Under it are Claude Code and Codex buttons. You only see a button for a tool HQ found installed on your computer. Click Claude Code to open your HQ folder there, then type /setup and press Return. If Claude asks whether you trust the folder, say yes, since HQ's commands only load once it's trusted.

You can also do this any time later. Open your HQ folder in Claude Code and type /setup.

Once setup finishes, Claude Code is ready to use with HQ.

Opening Claude Code later#

Whenever you want to work in HQ with Claude Code, click Launch in the top-right corner of HQ Desktop and choose Claude Code. The menu also has Codex (ChatGPT) and Grok Build (terminal).

If you have the Claude app, this opens its Code tab in your HQ folder. If you don't, it opens Terminal and starts Claude Code there.

The Launch menu opens Claude Code but doesn't install it or sign you in. If Claude Code isn't installed or signed in yet, see Step 1.

Once it's open, type HQ commands like /startwork, /search, or /deploy.

You can switch between Claude Code and Codex whenever you like. Both read the same HQ folder, the same instructions, and the same skills, so your work carries over between them.

Using the Claude Code command line instead#

If you don't use the Claude app, HQ also works with the command-line version of Claude Code.

• Install it: click Install Claude in Settings → AI tools. HQ installs it for you, including anything it needs to run.
• Sign in: click Connect Claude in Settings → AI tools and finish signing in in your browser. HQ notices on its own when you're done.
• Launch it: Launch → Claude Code opens Terminal in your HQ folder and starts Claude Code there, since the Claude app isn't installed.

The Claude app vs Terminal: one difference that matters#

HQ has automatic safety checks. They stop things like secrets being pasted into a chat, one company's files leaking into another's, and edits to HQ's protected core files. They also load the right company rules at the right moment and save your work automatically.

These automatic checks run when Claude Code is opened in Terminal. They don't run in the Claude app's Code tab. In the Claude app, Claude still reads HQ's safety rules and follows them, but nothing stops it automatically if it slips.

For everyday work, the Claude app is fine. For work involving passwords and keys, more than one company, or anything you can't undo, open Claude Code in Terminal instead:

1. Open the Terminal app.
2. Type cd followed by a space, drag your HQ folder into the window, and press Return.
3. Type claude and press Return.

More detail: im-stuck.md.

Plan mode#

Claude Code has a planning mode where it shows you a plan and waits for your okay before changing anything. HQ uses it for bigger tasks. Codex doesn't have this, which is one reason some people prefer Claude Code for large projects.

This is different from HQ's /prd command, which writes a project plan you can run later. (In HQ 16, /prd replaced /plan.)

Conduct mode#

In HQ 16, new sessions start in conduct mode by default: real work goes to background workers, so your session stays free. It only applies to sessions you start yourself, not to bots, fleet boxes, or scheduled jobs.

• To turn it off for a session, type /conduct off.
• To turn it off on this computer, copy core/settings/orchestrator.yaml to personal/settings/orchestrator.yaml and, under conduct:, set default_enabled: false.

More in The Daily Loop.

Troubleshooting#

"Claude Code was not detected."

HQ couldn't find the Claude app or the Claude Code command line. Install the Claude app from claude.ai/download, or click Install Claude in Settings → AI tools. Then try Launch again.

"Claude Code is not signed in on this Mac." (or "this PC")

Open Settings (click your picture at the bottom of the left rail and choose Settings, or press Cmd+,), go to AI tools, and click Connect Claude.

Setup opened, but /setup shows up as an unknown command.

The Claude app hadn't trusted your HQ folder yet when it opened. Accept the trust prompt, type /reload-plugins, press Return, then type /setup again.

"Sign-in timed out" or "Sign-in cancelled."

The browser sign-in didn't finish. Click Connect Claude again and complete the sign-in in the browser window that opens.

"Sign-in expired."

Click Sign in again next to Claude Code.

"Sign-in did not complete." during setup

Go back to the Your coding tools step and sign in again, then finish in your browser. If it keeps failing, you can pick a different coding tool, like Codex. One is enough.

"Could not install Claude Code on this Mac." or "Install failed. Check your network and try again."

Check your internet connection and try again. On Windows, antivirus or a permission prompt you can't see can also block it. If it keeps failing, download the Claude app from claude.ai/download. Then click Connect Claude in Settings → AI tools.

"Claude is taking longer than expected."

The Claude app didn't open your HQ folder on its own. Open the Claude app yourself, go to the Code tab, and open your HQ folder from there.

"HQ folder not configured yet, finish setup first."

The Launch menu needs a finished HQ folder. Finish the guided setup in HQ Desktop, or open your HQ folder in Claude Code and run /setup.

If you get stuck#

Work through im-stuck.md, or report it with /hq-bug. It packages the details for the team automatically. You can also switch to Codex for the moment (Launch → Codex (ChatGPT)) and come back to Claude Code later. Your work is the same in both.