/dm — Send or read an HQ direct message

Send a person-to-person notification through HQ, or read DMs from the CLI. On send, the recipient gets it as a macOS notification in their HQ Desktop App; if you attach agent context they get a one-click Copy prompt action, and if you attach details they get an Open details window. You can DM yourself (note-to-self / reminders).

hq dm is send and read. The HQ Desktop App still surfaces live notifications; the CLI can also list your inbox, open a 1:1 thread, and show channel / group history. You can only DM someone you share an active company with.

Usage

Send

hq dm <recipient> <message> [options]

• <recipient> — one of:
  • a teammate's email (e.g. stefan@example.com),
  • a personUid (prs_…) or agentUid (agt_…),
  • a bare name (e.g. stefan or Stefan Walsh) — resolved to the exact email before sending (see Resolve recipients below),
  • a comma-separated list of any of the above — this opens a group DM (every token is resolved independently). Your own email = a note-to-self, or
  • a named channel — bare (vyg-dev), hash form (#vyg-dev), or --channel <name> (see hq channels).
• <message> — the notification body (the headline the recipient sees). Required.

Options (1:1 DMs only — not channels/groups):

Option	Effect
--prompt <text> / --prompt-file <path>	Agent-context prompt the recipient can one-click copy into their own agent session. Only when present does the banner show Copy prompt.
--details <text> / --details-file <path>	Longer text shown in the recipient's Open details window.
--at <iso>	Schedule delivery at an ISO8601 time (store-and-forward — arrives even if you're offline at that time).
--in <duration>	Schedule after a relative delay: 30s, 10m, 2h, 1d.

Audience (every send: 1:1, group, channel):

Option	Effect
(none)	audience: agent. The message is for the recipient's agents and lanes; the HQ desktop folds it away from people by default.
--audience human (alias --for-human, hq-cli >= 5.345.167)	The message is for a person. It shows in their conversation, with a small CLI chip.
--audience both	For the person and their agent, for example a handoff with a prompt to copy.

When the user asks you to message a person, pass --audience human (or both when you also attach --prompt). Leave the default only for machine status that no person needs to read.

Read

DMs can be read from the CLI (hq-cli ≥ 5.70). Prefer these when the user asks to check messages, open a thread, list unread, or pull channel history — do not tell them DMs are receive-only in the desktop app.

hq dm inbox [options]
hq dm thread|read <person> [options]
hq dm channel|history <target> [options]

Command	Effect
hq dm inbox	List recent incoming DMs.
hq dm thread <person> (alias read)	Show the two-way 1:1 conversation with a person (email, prs_…, or agt_…). Oldest-first; marks their messages read unless --no-ack.
hq dm channel <target> (alias history)	Show recent messages in a named channel or group DM — by name, #name, or a channel id from hq channels.

Read options:

Option	Where	Effect
--limit <n>	all	Max messages to fetch (server-capped).
--unread	inbox	Show only unread messages.
--mark-read	inbox, channel	Mark fetched inbox messages read / advance the channel read marker.
--no-ack	thread	Do not mark incoming messages as read.
--json	all	Raw JSON instead of the list / transcript.

Examples:

# Unread inbox
hq dm inbox --unread

# Mark the page read after listing
hq dm inbox --mark-read

# 1:1 thread (alias: hq dm read …)
hq dm thread stefan@example.com
hq dm read prs_abc123 --no-ack --limit 50

# Channel / group history (alias: hq dm history …)
hq dm channel vyg-dev
hq dm history "#launch" --mark-read
hq dm channel chn_…          # unnamed group DM — id from `hq channels`

# Machine-readable
hq dm inbox --json
hq dm thread stefan@example.com --json

For a bare name on thread/read, resolve with hq people resolve first (same rules as send) — the read path only accepts email / personUid / agentUid.

Steps (send)

1. Resolve intent. From the user's request, pull the recipient(s), the message body, and any agent prompt / details / schedule. If the user said "send my agent context" or "so their agent can act," put that in --prompt. If they want a longer writeup, use --details. If they want to read messages instead, skip to the Read commands above.

2. Resolve & confirm recipient emails — never send blind. hq dm only accepts an email or a personUid — it does NOT look up names. So before sending, turn every recipient token into a confirmed email. First split the recipient on commas (a comma means a group DM); then resolve each token independently:

   • Fast path — already an email or personUid → use it verbatim. If the token contains @ (an email) or starts with prs_ (a personUid), pass it through unchanged. Do NOT look it up. This keeps every existing email/personUid invocation working exactly as before.

   • Name → resolve with hq people resolve (confirm before sending). Otherwise treat the token as a name and resolve it through the built-in people lookup (hq-cli ≥ 5.47.16) instead of sending to an unconfirmed recipient:

     hq people resolve "<token>" --json            # active company
     hq people resolve "<token>" --json --company <slug>   # when scoping explicitly
     

     This is single-company and tenancy-safe: it reads the active company's member roster (companies/<co>/people/*/meta.yaml) and never looks across company boundaries — HQ tenancy rules forbid cross-company member lookups. The active company is the sole non-archived company in companies/manifest.yaml; pass --company <slug> to scope explicitly. Read the JSON status field:

     • status: "found" → use the returned email. Resolution is confirmed; continue. (hq people resolve "<token>" without --json prints the bare email if you just want the address.)
     • status: "ambiguous" → STOP and disambiguate. Never guess. The result carries a matches[] array (the same set hq people search "<token>" returns); present those candidates (name · email · role) as a single decision and let the user pick — use the runtime structured picker (AskUserQuestion / Codex request_user_input), one question, plain-text numbered fallback if no picker is available (the decision-queue pattern). Use the chosen person's email.
     • status: "no_email" → STOP. The person was found but has no email on record. Tell the user plainly and ask for the exact email/personUid; do not send.
     • status: "not_found" → STOP. Say plainly that no teammate named "<token>" was found in the company, and that they can pass the exact email or personUid instead (or the person may not be in this company / not yet synced to this machine). Do not send a guessed recipient.
     • "Multiple companies" error (no --company given) → ask which company, then re-run hq people resolve "<token>" --company <slug>. Stay single-company; never fan the lookup across every company.

   After this step you hold a fully-resolved list of confirmed emails/personUids — one for a 1:1 DM, two or more for a group DM.

3. Humanize, then send. Before sending, run the channel-aware humanize pass on the message body (and any --prompt / --details text) per core/knowledge/public/hq-core/humanize-before-send.md — channel dm, default intensity light: strip the obvious AI tells but keep the message terse and conversational. Never rewrite recipients, scheduling flags, or anything that is not prose. Then run a single hq dm invocation with the resolved recipient(s). For a group DM, join the resolved tokens back into one comma-separated recipient string (a group needs at least 2 other people). Examples:

   # Plain DM (email — fast path, unchanged)
   hq dm stefan@example.com "Heads up — prod deploy going out at 3pm"
   
   # By name — confirmed to the teammate's email via `hq people resolve` first, then sent
   hq dm stefan "Heads up — prod deploy going out at 3pm"
   
   # Group DM — comma-separated recipients (each token resolved independently)
   hq dm "stefan@example.com,corey,prs_abc123" "Sync on the launch at 4?"
   
   # With agent context (recipient gets a Copy-prompt action)
   hq dm stefan@example.com "Can your agent take this over?" \
     --prompt "You are Stefan's agent. Pick up the acme-web deploy: merge #178, run the deploy script, verify routes."
   
   # With a details pane
   hq dm stefan@example.com "Review notes attached" --details-file /tmp/notes.md
   
   # Scheduled
   hq dm me@example.com "Stand-up in 10" --in 10m
   hq dm corey@example.com "EOD wrap-up reminder" --at 2026-05-29T17:00:00Z
   

   For multi-line or special-character prompts/details, prefer --prompt-file / --details-file (write the text to a mktemp file first) over inline quoting.

4. Report. Print the command's result — DM sent to <recipient> (eventId …) or Scheduled DM … for <time>. When you resolved a name, mention who it resolved to (e.g. "sent to Stefan Walsh stefan@example.com") so the user can confirm it reached the right person. On Recipient not found or not reachable, tell the user they can only DM someone they share an active company with (and to double-check the email / personUid).

Notes

• Name resolution is read-only, local, and single-company — hq people resolve only reads the active company's companies/<co>/people/*/meta.yaml roster, never mutates anything, and never looks across companies (tenancy-safe by construction). If a teammate isn't in that roster yet (not synced, or never recorded), pass their exact email/personUid; the name lookup is a confirm layer over the same hq dm. Use hq people search "<token>" to browse candidates, and --company <slug> to scope when you belong to more than one company.
• Requires a signed-in HQ session (/hq-login). The CLI resolves the caller identity from the Cognito token — a sent DM is always from the signed-in user; read commands show your inbox / threads.
• Read is first-class in the CLI (inbox, thread/read, channel/history). The Desktop App still delivers live notifications; use the CLI when the agent or user needs to inspect messages without the app UI.
• Scheduled DMs are promoted to live notifications within ~60s of their time on the recipient's next inbox poll.
• Never paste secrets into a DM body/prompt/details — DMs are stored server-side.
• hq dm sends with audience: agent unless told otherwise (hq-cli >= 5.345.167). A message a person must read needs --audience human or --audience both; without it the desktop app hides it in a fold and the person may never see it.

See also

• /hq-share — share a vault path in your message
• /delegate — a DM alone doesn't transfer work; use this to hand a whole project over (access, branch, secrets, ownership, and the pickup prompt in one flow)
• /signals — see action items and commitments
• hq channels — list named channels / group DM ids for hq dm channel