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

A worktree is not “another mode”; it is a second workspace under the same project. That is what lets you keep working on the main branch while an Agent tries another approach in an isolated directory.

​
Two workspace modes

Several Agents running in one Local workspace can edit the same file. Use a 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 session page.
  2. Choose the repository root in the directory browser (an in-app browser: ↑↓ to move, Enter to open, ⌘Enter to choose here, ⌘D to favorite the highlighted row).
  3. The Locations column has a Favorites group: favorites are newest first, up to twelve, and clicking again removes one.
  4. Confirm; Vibex opens the directory as a Local workspace.
Projects persist in the sidebar. Right-click one to customize its icon, create folders, enable Auto-continue, import sessions, or delete it.

​
Temporary sessions

The location picker on the new-session page offers Temporary session. It belongs to no project:
  • Useful for one-off questions, prompt tests, or tasks that do not need file access.
  • Still stored by the same authoritative runtime, and can be renamed, forked, and archived.
  • Switch to a project or worktree when the Agent needs workspace files or project commands.
  • A temporary session cannot create a worktree.

​
Create a workspace under a project

The location picker above the composer offers:
  • Local — work on the main checkout.
  • New Worktree — create an isolated workspace. It shows a Base branch picker (searchable) and Worktree settings:
    • Worktree name — derives the branch name vibex/<slug>.
    • Path — must be absolute.
    • Make this the project’s default — future sessions in this project create worktrees by default.
The worktree appears in the sidebar’s workspace view. Pick an existing worktree to continue a session there, or Finish one you no longer need.

​
Switch workspaces

Set Workbench → Sidebar hierarchy to Workspace view to list each workspace and its branch under a project. Switching workspaces does not copy uncommitted changes. The current session still belongs to the workspace where it was created; save files and check Git status before switching. If an editor buffer has unsaved changes, Vibex blocks the switch and asks you to save or discard. Every open or switch bumps a generation, so stale file, terminal, and Git requests are refused instead of writing into the wrong directory.

​
Worktree lifecycle

  1. Choose a base branch and name at creation.
  2. Start a session or edit manually in the isolated directory.
  3. Review changes in the Git panel and commit as needed.
  4. Choose Merge or Rebase. Resolve conflicts file by file (keep the target or source side), then Mark resolved. Abort merge cancels the merge.
  5. Discard the worktree only after confirming the result. Discard deletes the isolated directory and uncommitted changes.
You can also Rename worktree and Delete worktree. Mobile can view each managed worktree’s state, select one, and finish one; execution always happens on the authoritative side.
The worktree’s path, branch, and state are stored by the authoritative runtime. Remote v2 can request these operations, but the authority always performs them.

​
Session groups

A session group is a set of sessions under one worktree:
  • Multi-select sessions and choose New session group.
  • Split pane to view members side by side, or Merge panes.
  • The group header shows team state and member count; a collapsed group says how many sessions it holds.
  • Drag a group into a folder, swap it with another group, or drag it back to the workspace root.
  • Reorder members within the group; drag one out to remove it.
  • Dissolve session group does not delete sessions.
See Agent sessions.

​
Archive

Sessions under a project can be archived: they leave the sidebar but keep their full timeline.
  • Archive from a session row menu, the multi-select menu, or the bulk bar.
  • A folder row can set an automatic archiving idle window (off, or 1–14 days).
  • Settings → Archived sessions restores or permanently deletes.
  • Archiving is reversible; deleting is not.

​
File access boundary

  • The file tree, content search, and editor only access the current workspace.
  • The file service normalizes paths and checks symlinks, encoding, line endings, and size limits.
  • Agent tool calls are still permission- and capability-gated; opening a workspace does not grant every operation.
  • Terminals bind to the current workspace by default; you can also choose Open In → Terminal for a path in the file tree.
  • Remote requests carry workspace scope and generation; after reconnect, the authority’s state wins.

​
FAQ

​
Why can’t the Agent see a file I just created?

Confirm it was saved inside the current workspace, then refresh the file tree or reopen the session. A file outside the workspace must be moved in or attached.

​
Why does Git diff show no changes?

Check whether you switched to another workspace or worktree—Local and Worktree are different directories. Save the file and run git status --short in the terminal to compare.

​
Why can’t a session join a group?

A group can only contain sessions from one worktree. Move the session to the target worktree, or create a separate group.