# Project Workspaces

A **Project Workspace** is a named entry under Explorer's **Files → Project Workspace** page. It points at an absolute directory path on an Agent Host. The path is stored byte-for-byte — including any trailing space or casing — so what AgentTeam records matches what exists on the machine.

Project Workspaces are for codebases and working directories you return to often. For a quick look at what an agent is doing right now, use **Agent Directory** instead.

## Project Workspace vs. Agent Directory

|                   | Project Workspace                                   | Agent Directory                                                  |
| ----------------- | --------------------------------------------------- | ---------------------------------------------------------------- |
| What it points at | Any absolute directory you choose on a machine      | The agent's own working directory (`~/.agentteam/agents/<agent-id>/`) |
| Who creates it    | You, explicitly                                     | AgentTeam, automatically when the agent is created                    |
| Best for          | Browsing a codebase, running reviews against a path | Inspecting an agent's files, memory, and state                   |

## Create a Project Workspace

1. In the Explorer sidebar, open **Files → Project Workspace**.
2. Select a Project from the inline Agent Host-grouped resource list, or click **+** to create one.
3. Fill in two fields:
   - **Project name** — the display name shown in the project selector.
   - **Root path** — the absolute path to the directory.
4. Click **Create Project**.

New Project Workspaces are **private** to you with an empty description. You can change both later in Project Settings, along with visibility and member access.

Only the Project owner can remove it. The Settings tab keeps this action in a separate **Danger zone** and requires the displayed Project name before removal; an unnamed Project uses its displayed Root path instead. Removing a Project deletes its Explorer record and access grants, but never changes files on the Agent Host.

### Root path is byte-exact

Root path is stored exactly as you enter it. A path like `/home/user/repo ` (with a trailing space) is preserved so it resolves to the same directory on the machine. AgentTeam never trims the value.

### Browse or type manually

When the selected machine is online and its daemon advertises directory browsing, a **Browse** button appears next to Root path. Click it to open the machine directory picker and navigate folders without leaving your keyboard.

If Browse is disabled, the machine is either offline or running an older daemon. You can still type the absolute path manually — only Browse is disabled, not the Root path field.

## When Browse is unavailable

Browse requires the machine to be online and running a daemon that advertises the `machine.directory.list` capability. You will see Browse disabled in two common situations:

- **Machine offline** — the WS connection is down. Wait for reconnection or pick a different machine.
- **Older daemon** — the daemon was built before directory browsing shipped. Update the daemon on that machine to get Browse.

In both cases, type the absolute path into Root path and continue. Manual input is always available.

## After creation

The Files section provides separate **Project Workspace** and **Change Review** pages:

- In **Project Workspace**, select a project from the inline resource list to browse its directory tree and preview files. Selection automatically hides the list. The control to the left of the project name and path restores or hides it, and its divider can be dragged to adjust the remembered width. Owners and managers can open Project Settings from the same header to edit name, description, visibility, and member access.
- In **Change Review**, use the review surface's Review Context control to switch among available reviews.

## Open a shared Project Workspace

Project access and Agent Host management are separate permissions. If someone shares a Project Workspace with you but you cannot manage its host, the Files resource list still groups the shared Project under that host's identity without exposing a restricted host-management page. Available reviews remain accessible through the Change Review surface. You can browse the granted Project and Review, but you cannot create or change host resources. A loading indicator appears while AgentTeam checks project access; if the project list cannot load, use **Retry**.

## Errors you might see while browsing

If the machine directory picker cannot list a directory, it shows a short, path-free message. None of these include your path:

- **Invalid path** — the path is not absolute or does not resolve. Type an absolute path and retry.
- **Unreadable** — the machine could not read the directory. Check permissions or try another path.
- **Unsupported** — this machine's daemon does not support directory browsing. Update the daemon or type the path manually.
- **Unavailable** — browsing is temporarily unavailable. Retry or type the path manually.
- **Busy** — the machine is busy browsing. Retry shortly.
- **Too many folders** — the directory has more entries than the page can show. Type a more specific absolute path to narrow the view.