VCode home

Projects and Worktop

Agents: claude, codex, opencode, cursor · On: phone, desktop · beta

A project is a name and one or more folders on one computer. The first folder is MAIN: every tab you open in the project starts there, and its agent is told about the other folders. The window shows one project at a time: the strip, the swipes and the panes hold only its tabs. Worktop is the project that is always there. It holds every tab you start outside a project, from any folder on any computer.

Why you would use it

You work on several repos at once, each with a handful of tabs. With every tab in one strip, the tabs you need sit among tabs you do not. A project keeps one piece of work's tabs together, and its + opens a tab in MAIN straight away, with the agent you used there last. When the work spans repos, say an app and the server it talks to, one project holds both folders, and the agent knows where the other repo is.

How to use it

The tab bar

  1. Tap Tabs (#tabs-open), or pull in from the left edge of the transcript. The tab bar (#drawer) lists Worktop first, then your projects, each with its tabs under it.

    The tab bar: Worktop open with four tabs, and the notes project collapsed under it with its computer, its pencil, its tab count and its plus.

  2. Tap the chevron (.xchev) on a heading to open or close that project's list. Until your first tap on a chevron, the active project is the one shown open. From then on, which projects are open is kept on this device, and does not change when you switch project.

  3. Tap a project's name (.wsname) to switch to it. You land on the tab you last had open there, else its first tab. With a keyboard, Ctrl+Shift+PageDown and Ctrl+Shift+PageUp go to the next and previous project in the tab bar's order, Worktop first, and wrap at both ends.

  4. Tap a tab under another project to switch to that project and that tab in one step.

  5. On a wide window, drag the tab bar's right edge to make it wider or narrower. Double-click the edge to put the width back.

Make a project

  1. Tap New project (#drawer-new) at the bottom of the tab bar. The card (#newthread) opens headed NEW PROJECT, with the folder field open and no agent pick.
  2. In the app, pick the computer (.new-box). Picking another computer empties the folder list, since those folders are on the old one.
  3. Type or pick a folder in the field (.new-cwd) the way you do for a new thread: tap a row of its list, press Enter, or browse with the folder button. The folder joins FOLDERS (.project-folders) and the field closes. A folder still in the field when you tap Create project joins too.
  4. To add another folder, tap Add folder (.project-add) and pick again.
  5. The first folder is MAIN, marked with a blue star and Main (.project-main, titled New tabs start here). Tap the empty star, Make main (.project-make-main), on another folder to move it to the top. Tap the cross (.project-drop, titled Remove folder) to take a folder out. The last folder has no cross.
  6. NAME (.project-name) fills with MAIN's folder name and follows MAIN until you type in it. Type your own name to keep it.
  7. Tap Create project (.new-thread), or press Enter in NAME. A toast reads creating project… while the computer makes it.

The New project card: the computer, NAME holding ledger suite, three folders with ~/git/ledger marked with the star and Main, and the empty Make main star on the other two, Add folder, the hint line and Create project.

The card closes and the new project becomes the active one, open on its empty page. A new project goes to the end of the tab bar.

Each folder you add is taken to its repo: a worktree or a subfolder of a repo becomes the repo's main checkout. A folder outside git stays as it is. Two folders that land on the same repo count once. The same folder can be in several projects. Two projects with the same set of folders, in any order, cannot both exist.

Edit a project

  1. Tap the pencil (.wsedit, titled Edit project) on the project's heading. The tab bar closes and the card opens headed EDIT PROJECT, holding the project's name and folders.
  2. Rename it, add folders, remove them, or tap the empty star (Make main) to change MAIN. The computer is shown but cannot be changed: a project stays on its computer.
  3. Tap Save. A toast reads saving project… and the card closes when the computer has the change.

The Edit project card for ledger suite: the computer greyed out, NAME, the three folders with ledger as MAIN, Add folder and Save.

Tabs already open keep the folder they started in. A new MAIN applies to the next tab you open, and a folder you add reaches each agent the next time it starts.

Open a tab

Reorder and remove

  1. Hold a tab row and drag it up or down. It moves inside its project only. The strip and a pane's strip reorder the same way. See reorder-tabs.
  2. Hold a project's name and drag the heading to move the whole project. Worktop stays first and does not drag.
  3. A project stays when you close its last tab. Its heading then carries a cross (.wshead .wsclose, titled Remove project). Only an empty project can be removed, and Worktop never can. A done tab is still open, so a project holding one has no cross.
  4. Tap the cross. A popup (#confirm) titled REMOVE PROJECT asks Are you sure you want to delete this project? Its folders stay on disk. Tap Remove (#confirm-go) to remove the project. Cancel (#confirm-cancel), a tap outside the popup, back or Escape keep it.

The tab bar with the notes project empty: its count reads 0, and its heading has the pencil, a plus and the Remove cross.

The REMOVE PROJECT popup over the tab bar: Are you sure you want to delete this project? Its folders stay on disk., with Cancel and a red Remove.

An empty project

Switch to a project with no tabs, and the window shows an empty tab: a welcome line over the message box. Send a first message and the tab is made in the project's MAIN folder.

The empty notes project: a welcome line over the message box, with no tab in the strip yet.

What you see

Each heading shows, left to right: the chevron, the project's name, the computer it is on, a status dot while the project is closed and one of its tabs is working or waiting on you, the pencil, the number of tabs, and the plus. The active project's name is brighter than the others. Worktop's heading names no computer, since its tabs can be on any of them, and has no pencil.

An open project's tabs sit set in from both edges, with a thin rail on the left under the heading's chevron. The rail shows which tabs belong to that project. It is grey, and violet for the active project. Worktop has one too.

Under the last tab of an open project, Worktop included, sits a darker row with a dotted outline: a grey ring around a plus, and New tab where the tab names start. It does what the heading's plus does, so you can start a tab from the top or the bottom of the list. It does not drag and is not counted.

While a project is open in the tab bar, a line under its heading (.wsfolders) shows a folder icon and its folder's name. A project with two or more folders lists each one, MAIN first, joined with ·. A long line ends in an ellipsis.

The tab bar with ledger suite open: its pencil, count and plus, the line ledger · ledger-ui · notes under the heading, and its one tab, named ledger suite, led by the agent's mark, its status and model under its name, and no folder line, then the dotted New tab row.

A project tab's row in the tab bar shows its name and its agent and model, with no folder line: the project already says where it runs. A Worktop tab's row keeps its folder. In the strip, a project tab's second line is the project's name, with no folder icon; a Worktop tab's is its folder, after the icon. The Threads sheet has no folder button on a project tab's row, since a project tab does not move to another folder.

On a fresh device only the active project is open in the tab bar.

The window shows the active project's tabs and nothing else. The strip, swipes, the end pages past either end, and the tab that takes over when you close one all stay inside the project. A tab belongs to the project it was started in. A Worktop tab stays in Worktop even when its folder is in a project.

On a wide frame, each project keeps its own pane layout. Switch project and the panes swap. Switch back and you get the same splits, the same tabs in each pane, and the same focused pane. A project you have not split yet starts as one pane.

From 1080px of the frame's width, the tab bar is a column on the left, 264px wide, under the row of buttons on top. Drag its right edge to set it between 200 and 480px; double-click the edge for 264px again. The width is kept on this browser. Tabs then hides and shows the column, and lights up while it is showing. The choice is kept on this browser. Below 1080px Tabs opens the tab bar as a drawer.

The agent in a tab of a project with two or more folders is told the project's name and every folder's full path, with the one it started in marked, each time it starts. See what-the-agent-is-told.

Messages you may see:

Options and settings

Option Default What it changes
Name MAIN's folder name The heading's name and each new tab's name. 80 characters at most. Left empty, MAIN's folder name
Folders One at least. MAIN, the first, is where new tabs start. Every folder is named to the agent when there are two or more
Project order the order the projects were made Drag a heading to change it. Kept on this device; each computer also keeps the order of its own projects
Open projects the active project Which headings show their tabs. Kept on this device
Active project Worktop The project the window shows. Kept on this device with the tab last open in each project
Tab column (1080px and up) shown Tabs hides and shows it. Kept on this browser
Tab column width 264px Drag its right edge, 200 to 480px. Double-click the edge to reset. Kept on this browser

Limits and known gaps