# Projects

> The axis of parallelism: one repository, its board, its terminal.

A project is a git repository and its preferences. Each one has its own board, its own target terminal and its own sessions, and it is the thing devpit runs in parallel: the hard part of working with agents is not producing five versions of one feature, it is not losing the thread when you come back to a project two days later.

## Adding one

**Add a project** offers two ways in:

- **Open a folder**: "A repository already on this computer. devpit reads it where it is and never moves it."
- **Clone a repository**: a **Repository** URL, and **Into** for where it lands. The default is `~/.devpit/repos`.

You can reach it from the **+** at the foot of the project rail, from **Add project…** in the project picker, from **Settings → Projects → Add project**, and on first run. If a clone or an open fails, the sheet shows the reason it was given, such as a bad URL or a destination that already exists.

## Switching

The project rail down the left edge has one icon per project; click one to switch. The pill at the top left names the current project. Click it, or press ⌘P (Ctrl on Linux and Windows), and pick another. Each row says what is still running in that project, because switching does not stop anything: the previous terminal keeps running in the background and only stops taking up the screen.

To see every project's cards at once, use [the Manager](/docs/manager). To work across several with an agent, link them to an [orchestrator](/docs/orchestrators).

<!-- Screenshot — the project picker open, with a row saying what is still running in another project. -->

## Editing one, and groups

Right-click a project in the rail for **Edit project…**, **Reveal folder** and **Remove…**. **Edit project** holds its name, icon and colour, its **Group**, and what a new checkout is set up with — see [Worktrees](/docs/worktrees).

A group gathers projects under one heading in the rail, which folds like any other. Pick **New group…** in a project's **Group** field to make one, or drag a project onto a group's heading. Right-click the heading for **Show only active** — a project with open tabs, or the one you are in — **Rename group…** and **Ungroup**. The projects it hides show as **+N**.

## Settings → Projects

Every project, with its folder, its remote, when it was last opened and how many worktrees it has. Each row carries **Open**, **Rename**, **Reveal**, an **Open in** menu for your other apps, and **Remove**.

## Removing one

"Removing a project takes it out of devpit. The folder, the git repository and your code are never touched — devpit only forgets where it was." Its worktrees stay on disk as well, and the dialog says how many there are.

That dialog has one option: **Also delete this project's devpit workspace**, which deletes the board, its cards, its notes and its saved conversations under `~/.devpit/projects`. Your code is still not touched, and this cannot be undone.

## Its agent

A project can have an agent of its own, read-only, that answers about the project from a memory you approve: **Ask the project**, in its sidebar. See [The project agent](/docs/project-agent).

## Its workspace

Each project gets a folder at `~/.devpit/projects/<name>-<suffix>`, "holding its board, skills, capabilities, transcripts and worktrees. None of it is in the repository." See [Where your data lives](/docs/your-data).
