> ## Documentation Index
> Fetch the complete documentation index at: https://vibex.peatboy.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects and workspaces

> Choose, switch, and isolate the file, Git, and Agent scope in Vibex.

A **project** is a folder you register in Vibex; a **workspace** is "using this project in a particular way". One project can hold several workspaces at the same time.

A workspace is the boundary within which Vibex reads and writes files, runs terminals, and performs Git operations. The authoritative runtime stores workspace metadata and the current selection, and the workspace also determines which files an Agent can see.

## Hierarchy

```text theme={null}
Project
├── Local workspace (CurrentCheckout)   ← work directly in the main checkout
└── Worktree workspace (VibexWorktree)  ← isolated directory, several can coexist
        └── Session
```

In other words: **a worktree is not "another mode", it is a second workspace under the same project.** That is exactly why you can keep working on the main branch while an Agent tries another approach in an isolated directory.

## The two workspace modes

| Mode              | UI label                     | Behavior                                                                                                         |
| ----------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `CurrentCheckout` | **Local** / current checkout | Files and Git operations act directly on the main checkout directory; several sessions may see the same changes. |
| `VibexWorktree`   | **Worktree**                 | Vibex creates a managed Git worktree and provides merge, rebase, conflict handling, and discard flows.           |

<Warning>
  When several Agents run at once in a **Local** workspace, they can modify the same file. Use **Worktree** when you need parallel attempts or review.
</Warning>

## Open a project

1. Click **New project** in the sidebar, or use **Project directory** on the **New chat** page.
2. In the directory browser that opens, select the repository root. (This is an in-app browser that supports `↑↓` to navigate, `Enter` to open, `⌘Enter` to select here, and `⌘D` to star the highlighted row.)
3. The browser's **Places** rail carries a **Starred** group: starred folders are listed newest first, up to twelve, and starring again from the row or the rail removes one.
4. Once you confirm, Vibex opens that directory in **Local** mode.

Projects stay in the sidebar permanently. Right-click a project to customize its icon, create a folder, enable **Auto continue**, import sessions, or delete it.

## Create a workspace under a project

When you create a session, the location picker above Composer offers two options:

* **Local** — work on the main checkout directory.
* **New Worktree** — create an isolated workspace. Once selected, a **Base ref** picker appears (with searchable branches) along with the **Worktree settings** panel:
  * **Worktree name** — the branch name `vibex/<slug>` is derived from it.
  * **Path** — must be an absolute path.
  * **Default to a new Worktree for this Project** — future sessions in this project create a worktree by default.

## Switch workspaces

When **Workbench → Sidebar hierarchy** is set to **Workspace view**, each project lists its workspaces and their branches.

Switching workspaces does not copy uncommitted changes anywhere else. The current session still belongs to the workspace it was created in, so save your files and check Git status before you switch.

If the editor still has unsaved buffers, Vibex blocks the switch and asks you to save or discard them. Every time you open or switch a workspace the generation advances, and stale file, terminal, and Git requests are rejected so results never land in the wrong directory.

## Worktree lifecycle

| State         | Main actions                                                        |
| ------------- | ------------------------------------------------------------------- |
| **Working**   | **Review changes**                                                  |
| **Reviewing** | **Mark ready**                                                      |
| **Ready**     | **Merge** / **Rebase** (mapped to `NoFfMerge` and `RebaseAndMerge`) |
| **Queued**    | **Review merge**                                                    |
| **Archived**  | Restore                                                             |

1. Choose the base branch and name when you create the worktree.
2. Start a session in the isolated directory, or edit files by hand.
3. Review the changes in the Git panel and commit as needed.
4. Choose **Merge** or **Rebase**. When conflicts appear, resolve them file by file (for each file you can keep the target side or the source side), then click **Mark resolved**. You can give up midway with **Abort merge**.
5. Once you have confirmed the result, discard the worktree. **Discarding deletes the isolated directory and any uncommitted changes.**

You can also run **Rename Worktree** and **Delete Worktree** on a worktree.

<Info>
  The authoritative runtime stores each worktree's path, branch, and state. Mobile can request these operations over Remote v2, but the work itself always happens on the authoritative side.
</Info>

## File access boundaries

* The file tree, content search, and editor only reach the current workspace.
* The file service normalizes paths and checks symlinks, encoding, line endings, and size limits.
* Agent tool calls are still subject to permission and capability gating — opening a workspace does not automatically authorize every operation.
* Terminals bind to the current workspace by default, but you can also pick **Open In → Terminal** on a path in the file tree.
* Remote requests also carry the workspace scope and generation; after a reconnect, trust the state re-read from the authoritative runtime.

## Common questions

### Why can't the Agent see the file I just created?

Check that the file was saved inside the current workspace, then refresh the file tree or reopen the session. If the file is outside the workspace, move it inside first, or provide it as an attachment.

### Why doesn't the Git diff show my changes?

Check whether you switched to another workspace or worktree — `Local` and `Worktree` are completely different directories. Confirm the file is saved, then run `git status --short` in the terminal to compare.