Using HQ with Codex

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 Codex path. For Claude Code, see use-hq-with-claude-code.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 ChatGPT account. Codex signs in with your ChatGPT account.
• The ChatGPT desktop app (recommended). Codex comes built into it. You can get it at chatgpt.com/download. If you'd rather use the command-line version of Codex, see "Using the Codex command line instead" below.

Step 1: Connect Codex 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 Codex, and finish signing in in your browser. HQ notices on its own when you're done. You only need one coding tool, so Codex 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:

One thing that trips people up: being signed in to the ChatGPT app isn't the same as Codex being connected to HQ. Codex keeps its own sign-in. If Settings says "Installed, not signed in" even though ChatGPT is open and signed in, click Connect Codex anyway.

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 Codex.

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 Codex isn't installed yet, click Install Codex. If you have the ChatGPT app but haven't used Codex in it yet, click Open ChatGPT, use Codex 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 Codex. 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 Codex to open your HQ folder there, then type /setup and press Return.

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

Once setup finishes, Codex is ready to use with HQ.

Opening Codex later#

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

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

Codex opens in your HQ folder, and you type HQ commands the same way you would in Claude Code, 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 Codex command line instead#

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

• Install it: click Install Codex in Settings → AI tools. HQ installs it for you.
• Sign in: click Connect Codex in Settings → AI tools. It's the same browser sign-in as above.
• Launch it: Launch → Codex (ChatGPT) opens Terminal in your HQ folder and starts Codex there, since the ChatGPT app isn't installed.

How Codex differs from Claude Code in HQ#

Most of HQ works the same in both tools. A few things to know:

• Same brain, different assistant. Codex reads HQ's instructions from a file called AGENTS.md, which points to the same instructions Claude Code uses. Your companies, knowledge, and skills are shared.
• Safety checks. HQ runs its safety checks in Codex too (the automatic guards that stop things like secrets being pasted or one company's files leaking into another's). They help, but they aren't a guarantee.
• Codex doesn't stop to ask as often. HQ sets Codex up to run commands in your HQ folder without asking permission each time, so it can work through multi-step tasks. Keep an eye on what it's doing, and ask it to pause before anything you can't undo.
• No plan mode. Claude Code has a planning mode where it shows you a plan before acting. Codex doesn't. If you want a plan first, ask for one, like "Make a plan and wait for my okay before changing anything." For a full project plan, use /prd. (In HQ 16, /prd replaced /plan.)
• Conduct mode is on by default. In HQ 16, new sessions start in conduct mode. 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.
• Mac and Windows only. On Windows, Launch → Codex (ChatGPT) opens the Codex app if you have it, or opens a terminal window and starts Codex there. HQ doesn't run on Linux yet.

Already had HQ before Codex support?#

If your HQ folder is older and was set up only for Claude Code, Codex may not see HQ's skills. Open Claude Code in your HQ folder and run:

/convert-codex

It shows you what it would add first and only makes changes when you confirm. It only adds files and doesn't change your Claude Code setup.

Troubleshooting#

"Codex was not detected."

HQ couldn't find the ChatGPT app or the Codex command line. Install the ChatGPT app from chatgpt.com/download, or click Install Codex in Settings → AI tools. Then try Launch again. If you need to keep going right away, open your HQ folder in the ChatGPT app's Codex tab yourself and type /setup. HQ copies that command to your clipboard for you.

"Codex 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 Codex. Remember that signing in to the ChatGPT app doesn't sign Codex in to HQ.

"Sign-in timed out" or "Sign-in did not complete."

The browser sign-in didn't finish. Click Connect Codex in Settings → AI tools again and complete the sign-in in the browser window that opens.

"Sign-in expired."

Click Sign in again next to Codex.

Signed in, but it still isn't working?

Check Settings → AI tools. If Codex shows Installed, not signed in, click Connect Codex, since the ChatGPT app's sign-in and Codex's sign-in are separate. If it shows Ready and things still fail, quit HQ, reopen it, and try again. If it keeps happening, report it with /hq-bug.

"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 Codex and run /setup.

"Install failed. Check your network and try again."

Check your internet connection and click Install Codex again. If it keeps failing, install the ChatGPT app instead, since it includes Codex.

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 Claude Code for the moment (Launch → Claude Code) and come back to Codex later. Your work is the same in both.