# Team files

Open a team's folder in the Explorer, edit and save its files on the AI Team Cloud Computer, and search them with HQ's own search.



## Open a team's files [#open-a-teams-files]

<Steps>
  <Step title="Pick the team">
    In the HQ sidebar's **Teams** view, press the folder icon on a team, or right-click it and choose
    **Open Team Files**. **HQ: Open Team Files** in the Command Palette asks you to pick a team.
  </Step>

  <Step title="Work in the Explorer">
    The team's folder appears in the Explorer, named after the team and its organization, for example
    `Backend team (Acme)`. Its address starts with `hq://`. Open, edit and save files as usual; every
    save goes to the AI Team Cloud Computer.

    With more than one HQ account signed in, the name also shows the account, for example
    `Backend team (Acme) · owner@client`.
  </Step>
</Steps>

Opening a second team adds a second folder to the same window. Remove a folder from the window the
usual way (right-click it, **Remove Folder from Workspace**).

Changes made on the AI Team Cloud Computer, by an AI Employee or a teammate, show up in the editor within a few
seconds. If someone changed a file after you opened it, saving it says
"This file changed on the AI Team Cloud Computer. Save again to compare." Save again and the editor offers to
compare the two versions or overwrite.

## Folders and accounts [#folders-and-accounts]

A folder works as the account that opened it, whichever account the window uses now. Its address
carries that account (`hq://a3f9c01b7e2d4@acme/hq-3f9a1c2e/`), so it opens as the same account
after a reload, from **Open Recent**, or from a saved workspace.

* **The same team from two accounts.** If both of your accounts can reach a team, you can open it
  from each. They are two folders, each named with its account, each reading and saving as its own
  account. Save one and the other shows the change like a teammate's.
* **A folder whose account is not signed in** shows nothing and says "This folder belongs to
  [owner@client.com](mailto:owner@client.com), who is not signed in on this computer." with **Sign in as [owner@client.com](mailto:owner@client.com)**.
  Sign in as that account and the folder fills in, and a file you tried to open shows its
  contents, without a reload or a refresh. The message goes away once you are signed in. A file
  that could not open because the team was off opens by itself once the team is running. Only tabs that could not open come back this way (at
  the end of their group); tabs that were already open, or have unsaved changes, are left exactly
  as they are. A compare view or an image preview that could not open needs opening again. If you
  approve as someone else, the folder stays as it is.
* **Folders opened before version 0.2.0** have addresses without an account
  (`hq://acme/hq-3f9a1c2e/`). They keep opening as the account you used then.
* Folder names are saved in your `.code-workspace` file, so the short account name is too.

## When a file is read only [#when-a-file-is-read-only]

| You see                                                                             | Why                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "You can view this team but not change its files."                                  | You have viewer access to the team.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| "Your plan is read-only. Reactivate billing in HQ to save files or start sessions." | Your organization's plan does not allow changes right now.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| "This file came from an AI Workforce One HQ template, so it is read-only."          | On a team created from a template, `.claude/` and the template's manifest cannot be changed from any HQ app.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| "This file contains masked secret values. Edit it from an HQ terminal."             | The file holds a value from the team's secrets. You see it masked, as in HQ, so it cannot be saved from here. When you open it, the extension says which secret, for example "STRIPE_KEY", if you can use the team's terminals. A teammate's personal secret is masked too, but only its owner sees its name. Read the value from `$STRIPE_KEY` instead of keeping it in the file. When a secret is changed or removed in HQ, open files pick up the change by themselves within about 15 seconds. The old value stays masked for as long as the team exists, so text that still holds it is not shown in clear. |
| "This file is too large to open here. Open it in HQ or from a terminal."            | Text files up to 8 MB open here (binary files up to 64 MB). Files over 16 MB open read only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

## When the AI Team Cloud Computer goes to sleep [#when-the-ai-team-cloud-computer-goes-to-sleep]

An AI Team Cloud Computer nobody is using goes to sleep after a while, and wakes when someone comes back. VS
Code keeps it awake only while you are working with it: opening a team folder or a terminal while the
team is running, opening or saving a file, typing in a terminal, or using a forwarded port. A VS Code
window left open does not keep it awake, and neither does VS Code reconnecting by itself.

VS Code keeps the team awake while you open, read or save files; typing in an open file counts once
you save. VS Code 0.1 windows still count their hourly reconnects as you being there, until they are
updated to 0.2.0.

In HQ in the browser, a team page or a terminal counts while it is on screen and you are at it: the
window has focus, or you used the mouse, keyboard or touch screen in the last 10 minutes.

What else keeps a Cloud Computer awake, including a question Claude asked that nobody answered, is
in [When a Cloud Computer sleeps](/docs/ai-teams/sleep/).

## When the AI Team Cloud Computer is off [#when-the-ai-team-cloud-computer-is-off]

Folders and files you already opened stay readable. Opening a new file, or saving, says, for example,
"Backend team is off. Wake it to open this file." (or "to save this file") with a **Wake Team**
link. Opening and reading files never wakes an AI Team Cloud Computer by itself.

Once the team runs again (woken here, in HQ, or by a session), the notice closes by itself, and a
file or folder that failed while it was off opens on its own, with no **Try Again** or **Refresh**.

If the Cloud Computer is updating, the extension says when its files are back. If it needs an update
first, the team shows `update needed` and the extension offers **Open Team Settings**, where a
team owner (or an organization owner or admin) presses **Update Cloud Computer**.

## Search a team's files [#search-a-teams-files]

<Steps>
  <Step title="Start the search">
    Right-click a team and choose **Search in Team Files**, or run **HQ: Search in Team Files**. With an
    `hq://` file open, the search runs on that file's team.
  </Step>

  <Step title="Type the text">
    Type what to find, then pick options: **Match case**, **Whole word**, and **Regular expression**
    when you can edit the team. Then, optionally, the files to include and to exclude, as
    comma-separated patterns such as `src/**, *.ts`.
  </Step>

  <Step title="Open a result">
    The results appear in the **Search** view of the HQ sidebar, grouped by file. Click one to open the
    file at that line.
  </Step>
</Steps>

The search runs on the AI Team Cloud Computer, so it covers every file, not only the ones you opened. A line
that holds a secret value is left out of the results. When there are too many results, the view
says "more were found; narrow the search".

## Good to know [#good-to-know]

* Editors give team files basic support: syntax colors everywhere, and TypeScript and JavaScript
  features for the files you open. Language servers that need local files, such as most Python, Go
  and Rust tools, do not work on team files. Use a session terminal to run builds and tests.
* The extension never runs anything from team files.
* File contents are kept in the editor's memory only, never on this computer's disk, and are
  cleared when you sign out of the account they belong to.
