Worktrees

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

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:

Open, list, remove

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:

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

An empty value keeps the sibling-directory default; a relative path is resolved against the repo. See Configuration.

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:

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:

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

See also

• Restore and resume — worktree sessions are snapshotted too
• tmux chrome — worktree sessions arrive pre-adopted
• Multi-agent teams — dispatch work to each worktree's agent