Local Bots

In HQ, every AI teammate is a bot. You message a bot the same way you message a person, and it does the work using HQ's knowledge, skills, and your files.

There are two kinds:

This page covers local bots. For cloud bots, see Cloud Bots.

You already have one local bot: your HQ assistant. You named it on the first setup screen (Name your HQ assistant.), and that name is what you'll see in your Home list. It stays around afterward, so you can ask it "how do I…" questions.

Before you start#

You need at least one AI tool connected: Claude Code, Codex, or Grok. Check in Settings → AI tools. To open Settings, click your picture at the bottom of the left rail and choose Settings, or press Cmd+,. See Using HQ with Claude Code or Using HQ with Codex.

Creating a local bot#

Start a New bot. Press Cmd+Option+N (Ctrl+Alt+N on Windows), click the + button in your Home list and choose New bot, or go to Settings → Bots and click New bot. Then:

1. Name. Type a name for your new teammate. This is how it appears in HQ, and teammates mention it by its handle, like @research-helper.
2. Where should <name> live? Pick Local (runs on this machine, free). Cloud makes a cloud bot instead; see Cloud Bots. If the bot already runs somewhere else, click Connect it under the two choices for the steps to link it.
3. Coding tool. Choose which tool it thinks with: Claude Code, Codex, or Grok. It uses your own plan for that tool. If the tool isn't signed in, click Sign in. This is the only step after the name that you have to answer.
4. Who it's for. Personal or Company. See the next section.
5. Start from. Pick Blank for a general helper with your permissions, or one of your company's workers, like a writer or a researcher.
6. Fine-tune. Change the handle, permissions, or memory if you want to. See Fine-tune options below.

Each screen has a Next button (it names the next step, like Next: Who it's for) and Finish with defaults, which creates the bot right away and keeps the defaults for every step you skipped. On the last screen the button reads Create followed by the bot's name.

It takes about half a minute. A new local bot runs a quick readiness check before it's saved, so you know it works. In its first message it asks you three things: its job title, what avatar or look you'd like, and whether you have a model preference.

Personal or company bot

This is the most important choice:

• Personal: acts as you. The bot works under your account and can reach everything you can. It stays on your computer, and teammates can't find it or add it to their own channels.
• Company. The bot gets its own identity and can only reach its companies' files. Teammates in the company can tag it in their conversations. A company bot can later move to the cloud. If you're in more than one company, pick which ones it belongs to.

A new bot starts as Personal unless you started it from a company's page. If you're not sure, use a company bot for team work and a personal bot for your own tasks.

Fine-tune options

On the Fine-tune screen, you can change:

• Handle. How the bot is mentioned, like @research-helper, and what the hq command line calls it. It follows the bot's name unless you change it.
• Permissions. Pre-approve every action (the default) lets the bot run tools and commands without asking. Only keep this for bots you trust with your files. Ask before each action is the safer option, but a bot can't answer approval prompts, so actions that need approval will fail.
• Memory. HQ synced (the default) lets its memory follow you to your other computers. This Mac only keeps what the bot learns on this computer.

Talking to your bot#

Your bot appears in your Home list under Direct messages once it's sent its first message. Open it and type, like any other conversation.

You can also bring a bot into a group or project channel. Type its name, like @research-helper, to get its attention. Bots don't respond to @here, so always use their name.

If a personal bot is in a channel, everyone there can tag it, but it's still yours. Nobody else can add it to their own channels.

You can message your bots from your phone too, as long as the computer they run on is on.

Starting, stopping, and removing a bot#

Click a bot's name to open its profile. From there you can:

• Start or Stop it.
• Remove it.
• Rename it. In a terminal, run hq bot set --display-name with the new name.
• Promote to cloud (company bots only). This turns it into a cloud bot that runs even when your computer is off, and keeps its name, conversations, skills, and memory. It uses company credits.

If you message a bot that's stopped, HQ starts it for you.

If a bot's coding tool fails, the bot shows a card with one button to fix it: Sign in, Update, Use a supported model, or Try again.

Settings → Bots lists every bot you work with, grouped into Local, Cloud, and bots on your other computers. Each shows a status:

Moving to a new computer#

If you reinstall HQ or set up a new computer, your bots come back on their own. If one doesn't, go to Settings → Bots and click Restore my bots. HQ never moves a bot off a computer where it's still running.

Common questions#

If you get stuck#

See The "I'm Stuck" Guide, or report it with /hq-bug. It packages the details for the team automatically.