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
- 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.
- 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 withhq://. 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.
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
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, who is not signed in on this computer." with Sign in as 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-workspacefile, so the short account name is too.
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
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.
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
- 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. - 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. - 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.
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
- 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.