# Sessions, branches and worktrees

> Every session works in its own copy of the project, so any number of agents can work at once.

Source: https://sesh.codes/docs/branches-and-worktrees/

When you start a session in a git project with **New branch** on, Sesh gives the agent its own branch and its own working folder (a git worktree). Your checkout is never touched, and two agents in the same project never step on each other's files.

## What happens when a session starts

1. Sesh makes a branch from the session's name, like `sesh/add-dark-mode`.
2. It starts the branch from the latest base branch on the remote, usually `main`.
3. It creates a separate folder for the branch, outside your project.
4. It copies files git doesn't track, like `.env`, into that folder.
5. It runs a setup command, such as `npm install`, and shows the output as a **Setup** card in the chat.
6. The agent starts on your task.

If setup fails, the card turns red and the agent starts anyway. It can often fix the problem.

Sesh guesses the setup command from your lockfiles. To choose it yourself, see [Project setup](https://sesh.codes/docs/project-setup.md).

## Work in the folder instead

Turn off **New branch** in **New Session** to run the agent right in the project folder, on whatever branch is checked out. Use it for quick questions, or for folders that aren't git repositories. **New branch** only shows for git projects.

## Rename a session

1. Right-click the session in the sidebar, or open the **⋯** menu in its toolbar.
2. Choose **Rename…** and type a new name.
3. Leave **Rename the branch too** on to rename the branch to match.

A branch that's already pushed keeps its name.

## Archive a session

Choose **Archive** from the session's menu. The agent stops and the session moves to **Archived** at the bottom of the sidebar. The branch, the folder and the whole conversation are kept.

To bring it back, choose **Unarchive**, or send it a message.

## Delete a session

1. Choose **Delete…** from the session's menu.
2. Read what Sesh says would be lost: changes that aren't committed, and commits that aren't pushed.
3. Choose whether to **Delete the branch too**. It's off when the branch has unpushed commits.
4. Click **Delete**, or **Archive Instead** to keep everything.

The session's folder is always removed. Your project folder is never touched.

## Find the files

- **Reveal in Finder** in the session's menu opens its folder (for sessions on this Mac).
- **Copy Branch Name** copies the branch, for checking it out yourself.
- **Open In** opens the folder in Cursor, VS Code, Zed, Xcode or Finder. Sessions on other machines open over SSH.

## Good to know

- There's no branch picker in **New Session** yet. Sessions start from the base branch, which you can set in [.sesh/config.json](https://sesh.codes/docs/project-setup.md).
- Setup can't be cancelled and has no time limit.
- Sesh names sessions with the on-device model, so the name and branch come from your task.
