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.
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
- 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.
- Attach
Run
hq attach <session>. Add--team <t>when the same name exists in more than one team. - 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# 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-echoWhen 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 detachLocal 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.
| Setting | Behavior |
|---|---|
--local-echo or --local-echo=auto | Echo locally only while the round trip is slower than 60 ms. |
--local-echo=always | Echo locally at any speed. |
--local-echo=off | Never. 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.