Skip to main content
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

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

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.

​
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

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

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