# 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.



<Callout title="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.
</Callout>

## How it works [#how-it-works]

<Steps>
  <Step title="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.
  </Step>

  <Step title="Attach">
    Run `hq attach <session>`. Add `--team <t>` when the same name exists in more than one team.
  </Step>

  <Step title="Detach when you're done">
    Press `Ctrl-]`. The session keeps running; you can attach again any time.
  </Step>
</Steps>

<Tabs items="['macOS / Linux', 'Windows']">
  <Tab value="macOS / Linux">
    ```bash
    # 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
    ```
  </Tab>

  <Tab value="Windows">
    ```powershell
    # 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
    ```
  </Tab>
</Tabs>

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

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

## Local echo [#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.

| 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 [#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 [#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.

## Related [#related]

<Cards>
  <Card title="Port forwarding" href="/docs/cli/port-forwarding/">
    Reach a port on the AI Team Cloud Computer locally.
  </Card>

  <Card title="Troubleshooting" href="/docs/cli/troubleshooting/">
    Fixes for common attach and login errors.
  </Card>
</Cards>
