# Worktrees

> Run parallel agents on parallel branches: tmux-ide worktree creates a git worktree and a ready tmux session in one command, then lists and removes them.

`tmux-ide worktree` creates a git worktree on a new branch and opens a tmux
session in it, in one command. Use it to run two agents on two branches at once
without them touching each other's files.

## Create a worktree and session

```bash
tmux-ide worktree create fix/login
```

This adds a git worktree on a new `fix/login` branch and opens a session inside
it. If the worktree has a `.tmux-ide/workspace.yml`, that layout launches;
otherwise you get a plain session. Either way the session is adopted, so it gets
tmux chrome and is covered by notifications and restore snapshots right away.
The app shows it like any other tmux session.

Options:

| Flag           | Effect                                                     |
| -------------- | ---------------------------------------------------------- |
| `--from <ref>` | Base the new branch on `<ref>` instead of the current head |
| `--dir <path>` | Override where the worktree is checked out                 |
| `--no-session` | Create the worktree only; don't open a session             |

## Open, list, remove

```bash
tmux-ide worktree open fix/login            # open (or switch to) its session
tmux-ide worktree list [--json]             # worktrees joined with session status
tmux-ide worktree remove fix/login [--force]  # kill the session + remove the worktree
```

`remove` refuses to discard a dirty worktree unless you pass `--force`.

## Where worktrees live

By default each worktree is checked out into a sibling `<repo>-worktrees`
directory next to the repo. Override the base globally in
`~/.tmux-ide/config.json`:

```json
{
  "worktrees": {
    "dir": "~/wt"
  }
}
```

An empty value keeps the sibling-directory default; a relative path is resolved
against the repo. See [Configuration](/docs/configuration#other-sections).

## Example: one agent per branch

Each worktree gets a session named `<project>@<branch>`, with `/` replaced by
`-`. The project is the workspace `name`, or the repo folder name. In a repo
folder named `myapp`:

```bash
tmux-ide worktree create feat/api   # session myapp@feat-api
tmux-ide worktree create feat/ui    # session myapp@feat-ui
```

Start an agent in each session, for example `claude`, then wait for one to
finish:

```bash
tmux-ide wait agent-status myapp@feat-api --status done
```

## See also

* [Restore and resume](/docs/restore-resume) — worktree sessions are snapshotted too
* [tmux chrome](/docs/the-dock) — worktree sessions arrive pre-adopted
* [Multi-agent teams](/docs/multi-agent-teams) — dispatch work to each worktree's agent