Projects and repositories
Group repositories into a project, choose the machine each one runs on, and find a repository again when it moves.
A project is a named set of repositories you work on together. Its team, task board, plans, roadmap, architecture and memory sit above the repositories and work across all of them. Most projects have one repository; a project with a front end and an API has two.
Each repository lives on a machine, which is also where its agents run:
| Machine | When to use it |
|---|---|
| This computer | A folder on this computer. The simplest place to start. |
| WSL distro | Windows only. A folder inside a Linux distro; the agents run in Linux while the app stays a Windows app. |
| Dev container | A folder with a devcontainer.json. The container is built and the agents run inside it. Needs Docker. |
| Over SSH | A folder on another computer in your SSH config. The agents run over there; the workbench installs what it needs there itself. |
| AI Workbench node | A node your organisation assigned to you. The repository is cloned there and the agents run there. Shown when you are signed in to an organisation or have a node assigned. See Nodes. |
Create a project
Choose Add project… in the project switcher in the title bar, or New project from the Projects view. The wizard asks for a Project name and colour, then Where the repository lives, then its Source:
- Clone a repository: from GitHub, Azure DevOps or any git URL. Signed in under Settings → Integrations → Accounts, you can pick from your repositories.
- Existing folder: code that is already there. The wizard says whether it is a git repository, its remotes, whether it declares a dev container, and whether it carries workbench settings from someone else.
- New folder: made for you as a local git repository with a first commit. It needs no remote; you can Connect a remote later.
Then Prepare clones or creates it and starts the workbench there, Tools checks the agent tools on that machine, and Team offers a first team. The install tutorial walks through it.
If a folder you pick is already in another project, the wizard offers to open that project instead.
Add a repository to a project
Choose Add Root Folder… from the File menu (Ctrl+Shift+O, or ⌘+Shift+O on a Mac). The same wizard opens at Where, with the project already chosen.
The project switcher
The switcher in the title bar shows This project with its repositories and whether each is Running, Starting, Not running or Stopped with an error, then your recent projects with a search box. Ctrl-click (⌘-click on a Mac) opens a project in a new window. All projects… opens the Projects view.
The Projects view
Projects lists every project on this workbench and what each is doing now: agents running, tasks in review, approvals waiting for you, and today's spend. Switch between Detailed, List, Grid and By machine views, search, filter and sort.
When a repository moves
If a repository's folder is moved or deleted, Projects marks it and offers:
- Locate…: point it at the folder's new place. Its history comes with it.
- Clone again: if it came from a remote.
- Remove: take it out of the project.
Find it again searches the machines this workbench knows for a repository whose machine is gone too, such as a WSL distro reinstalled under a new name, by its git remote and project details. Several repositories that lost the same distro move in one step.
Where a project's records are kept
A project's own records (its roadmap, project board, architecture, memory index and activity) are kept at its home, never in a repository:
| Project | Kept by |
|---|---|
| Your own (Personal space or Free) | This computer |
| Shared with your team hub | The team's hub |
| Your organisation's | The organisation, with only caches on this computer |
The Projects view groups projects that come from elsewhere under From your organisation or From your team.
Getting work back to main
Agents work on their own branches and worktrees; nothing reaches main behind your back. When a plan is complete, Plans shows how far its branch is ahead with Merge into main and Open pull request. Source Control shows the branches agents made, and its Pull requests tab lets you review, comment, approve and merge pull requests on GitHub, Azure DevOps, GitLab, Forgejo, Gitea and Bitbucket.
Related
- Sign in and spaces: a folder belongs to one space.
- Back up and restore: move projects to a new computer.
- Memory