AI Workforce OneHQDocs

Attach to a session

hq attach joins an HQ session in this terminal, streaming its output live. Only the session owner can type; everyone else watches.

Only one typist.

The person who started a session is the only one who can type in it. Everyone else who attaches watches it live, view only. To work yourself, start your own session in HQ.

How it works

  1. Find the session

    Open the team in HQ: its session list shows each session's name. You can attach by that name or by the first characters of the session id.

  2. Attach

    Run hq attach <session>. Add --team <t> when the same name exists in more than one team.

  3. Detach when you're done

    Press Ctrl-]. The session keeps running; you can attach again any time.

# attach to a session by the start of its id
hq attach 7c21e0b4

# show what you type instantly, before the round trip confirms it
hq attach 7c21e0b4 --local-echo

When it connects, hq tells you whose session it is and whether you can type:

Attached to "fix login bug" (Dana) · you can type · Ctrl-] to detach

Local echo

On a slow connection, --local-echo draws your keystrokes the moment you press them, instead of after the round trip to the AI Team Cloud Computer. It only applies when you can type and your terminal is a real terminal.

SettingBehavior
--local-echo or --local-echo=autoEcho locally only while the round trip is slower than 60 ms.
--local-echo=alwaysEcho locally at any speed.
--local-echo=offNever. This is the default.

Set HQ_LOCAL_ECHO=auto in your shell profile to make it your default; the flag wins over it. Your organization has to allow local echo; when it does not, hq says so once and attaches without it.

When the AI Team Cloud Computer is sleeping

Attaching usually wakes it, and hq prints progress while it starts: usually 15-30 seconds for a wake (30-45 seconds on Boost Max, 120-180 seconds on the sizes from 80 GB), about a minute when it has to start fresh, and it gives up after 3 minutes (4 minutes on the sizes from 80 GB). If you see Press any key to continue., the Cloud Computer was not woken for you; the next key you press wakes it.

HQ's connections are renewed about once an hour: hq moves to a fresh connection before that happens, with nothing printed and no keystroke lost. If the connection drops anyway, hq reconnects on its own, up to 8 times in a row. It prints hq: connection lost, reconnecting... only when reconnecting takes more than a few seconds or the connection drops again.

The same session in two places

A session has one terminal size on the AI Team Cloud Computer, and the place you are typing in sets it. When the same session is also open in HQ in your browser or in VS Code, and you type in hq, the session takes your terminal's size. When you switch to the other place, the session takes its size, and hq redraws its screen at your terminal's size so nothing overlaps. Lines the session draws after that are laid out for the other place until you type in hq again.

If you resize your terminal while Claude Code is writing an answer, the session takes the new size when it stops writing text, and never more than 30 seconds later. That keeps the part of the answer that has already scrolled up from being drawn twice in the session's history. Your terminal resizes at once, so until the session catches up a few lines can be laid out for the old width. At a prompt the first size change applies at once. Codex sessions always change size at once.