Knowledge Hub

The HQ Knowledge Hub

Plain-English guides to HQ, from your first install to rolling it out across your whole team.

All articles
On this page
What you needSet it upWhat you can doStaying in controlCommon questionsIf you get stuck

Daily Use

iMessage in HQ

2 min read Updated Oct 2026

Mac users who want their local HQ bot to read the texts that come to them and reply as them.

The iMessage pack connects HQ to the Messages app on your Mac. Your local bot can read the iMessages that come to you and send replies as you. Ask it to pull up what a client sent, draft a reply, or send the follow-up you keep forgetting.

There's no extra service, no new phone number, and nothing to pay for. It uses your own Messages account. Everything runs on your Mac, and your messages don't go through any HQ cloud service.

What you need#

  • A Mac that's on and signed in to Messages with your Apple ID.
  • A local bot, or Claude Code or Codex on that Mac. iMessage works with local bots only, not cloud bots.
  • For phone numbers (green bubbles): Text Message Forwarding turned on on your iPhone for this Mac.

Set it up#

  1. Install the pack. In the HQ desktop app, click Marketplace on the left rail, search for iMessage, and click Install for me. From a terminal, you can run hq install marketplace:imessage instead.
  2. Allow Full Disk Access, so HQ can read your messages. Open System Settings, then Privacy & Security, then Full Disk Access, and turn it on for the app you run HQ in.
  3. Allow control of Messages, so HQ can send. When macOS asks if the app "wants to control Messages," click Allow.

The full walkthrough, with troubleshooting, is in Getting Texts from Your AI with iMessage.

What you can do#

  • Catch up: "What did Dana text me this morning?"
  • Draft a reply: "Draft a reply to the last message from my landlord. Don't send it yet."
  • Send a follow-up: "Text Sam that the deck is ready."
  • Get updates on your phone: "Text me when this build finishes, and watch for my reply."

Before it sends anything, it shows you who it's texting and the exact message, and waits for your okay.

Once it's installed, you can also start it directly with /imessage.

Staying in control#

  • A text you get is treated as information, not a command. Someone texting you can't make your bot do something you wouldn't approve.
  • A bot running on its own can only text people on an approved list, and only you can add people to it.
  • When it watches for replies, it only picks up messages that arrive after it starts watching.

Common questions#

Does my bot get its own phone number?

No. It uses your Messages account, so replies come from you.

Does it work when my Mac is asleep or off?

No. Your Mac has to be on and signed in to Messages.

Does it work on Windows?

No. It's Mac only.

Does it cost anything?

No.

If you get stuck#

If it can't read your messages, Full Disk Access isn't on for the app you run HQ in; turn it on, then quit and reopen the app. If sends are refused, open System Settings, then Privacy & Security, then Automation, and turn on Messages for that app. More fixes are in Getting Texts from Your AI with iMessage. Still stuck? See The "I'm Stuck" Guide, or report it with /hq-bug.