# Projects and worktrees
> Open repositories as projects and give each task its own worktree.
A **project** is a folder you open in Rexa, usually a git repository. A **worktree** is a separate checkout of that repository on its own branch, created with `git worktree`. Each worktree has its own tabs, terminals and agents, so parallel tasks never share files.
The **Projects** sidebar on the left lists projects, their worktrees, and the agents running in each worktree.
## Open a project
- ⌘ O, or the `+` folder button in the Projects header, opens a folder picker.
- `rexa open [path]` opens a folder from a terminal and launches Rexa if needed. See the [CLI](/docs/reference/cli).
What you pick decides what Rexa opens:
| You pick | Rexa opens |
| --------------------------------- | ------------------------------------------------------------------ |
| A repository root | The project with every worktree git knows about, wherever it lives on disk. |
| A folder outside any repository | A single-row project with no worktrees. |
| A folder inside a repository | A prompt: open just that folder, or the repository root. |
| A folder holding several repositories | A checklist of the repositories found up to three levels deep. |
A **subfolder project**, such as `packages/api` in a monorepo, limits the file tree, git changes, language servers and sessions to that folder. It cannot create or delete worktrees; its menu has **Open Repository Root**.
Opening a path that is already open selects the existing project.
## The sidebar
- **Drag** projects, worktrees and agent cards to reorder them. Click a project to collapse it. Order and folding are saved.
- **Rename** a project or worktree to change its display name. Clearing the name brings back the folder name.
- **Hover a project** for its path, worktree count and session counts.
The sidebar takes the keyboard when focused:
| Action | Shortcut |
| --------------------- | ----------------------------------------------- |
| Move | J K or ↑ ↓ |
| Open | Space |
| Rename | ↵ |
| Collapse / expand | H / L |
| Copy path | ⌘ C |
| Reveal in Finder | ⌘ ⇧ R |
| Hide | ⌘ ⇧ H |
| Move row up / down | ⌥ ↑ / ⌥ ↓ |
## Create a worktree
### Open the form
Press ⌘ ⇧ N, click `+` on a project row, or choose **New Worktree** from the project's right-click menu.
### Fill in the fields
| Field | Meaning |
| -------- | ------------------------------------------------------------------------ |
| Base | The branch to start from. Defaults to the main checkout's branch. |
| Branch | The new branch to create. Required. |
| Name | The folder name. Follows the branch, with `/` turned into `-`, until you edit it. |
| Location | The parent folder. Defaults to the folder that holds the project. |
Keep **Remember for this project** checked to reuse the location next time.
### Create
Rexa runs `git worktree add -b / `. The new worktree appears in the sidebar, selected. Git errors show inside the form.
Worktrees you add, remove or prune with `git worktree` in a terminal show up in the sidebar without a restart.
## Switch worktrees
| Action | Shortcut |
| -------------------------------- | ------------------------------------------------- |
| Worktree picker | ⌘ ⇧ W |
| Next / previous worktree | ⌘ ` / ⌘ ~ |
| Next / previous agent in the worktree | ⌃ ` / ⌃ ~ |
| Go back / forward | ⌃ - / ⌃ ⇧ - |
Typing `~` in quick open (⌘ P) also lists worktrees, grouped by project.
## Remote status
Each worktree row shows `↑N` for commits not pushed and `↓M` for commits not pulled. When the branch has a pull request, the worktree icon shows its state: open, draft, merged or closed. The main worktree has its own icon.
- **Counts update after a fetch.** Turn on background fetch with `git.autofetch` in Settings → Git.
- **Pull request state** needs the GitHub or GitLab CLI. See [Pull requests](/docs/review/pull-requests).
- **Hide both** with `git.remote_status` or the palette command **rexa: toggle sidebar remote status**.
### Reset a merged worktree
When a worktree's pull request is merged or closed, its menu offers **Reset Remote Status**. Rexa fetches and moves the worktree to the base branch on a detached HEAD, ready for the next task. The branch and its commits are kept. **rexa: reset all remote status** does this for every eligible worktree at once.
Reset asks first. If the worktree has uncommitted or untracked changes, the confirmation says they will be lost.
## Hide a worktree
**Hide Worktree** removes a worktree from the sidebar and leaves it on disk. Bring it back from the eye icon on the project row, or **Hidden Worktrees…** in the project menu.
## Delete a worktree
**Delete Worktree** in a linked worktree's menu removes its folder from disk. The main worktree cannot be deleted this way.
The confirmation lists what happens before you agree:
- The worktree folder is removed. Its branch and commits are kept.
- Agent sessions running in it are closed.
- Uncommitted changes and untracked files in it are lost.
## Remove a project
The project menu has two removals. Both are refused while agents are running in the project.
- **Remove from Rexa** forgets the project. The folder stays on disk.
- **Move to Trash** moves the project folder to the macOS Trash. Linked worktrees outside the folder are left alone.
## Toolchains and environment
Terminals, agents and language servers in a worktree get the project's toolchains: the active Python `.venv` and the Node version from `.nvmrc`, `.node-version` or `volta.node` come first on `PATH`. Pin a different one per project in [`.rexa/config.json`](/docs/reference/project-config) or from the language server status in the status bar. See [Language servers](/docs/workspace/language-servers).