Create a worktree
Press + in the Worktrees column, choose Worktree in the + of the repository’s
board, or press ⌥⌘P and pick Worktree. The New Worktree dialog has three modes.
| Mode | What you get |
|---|---|
| Plain | Just a branch with its own checkout: a New branch from the base, or an Existing branch of the repository. No agent. |
| Task | You explain what you want to fix or build, and an agent starts on it. |
| GitHub | Pick an open issue or pull request. The worktree is linked to it, and an agent starts unless you tick Start without agent. |
Name, branch and base
Section titled “Name, branch and base”The Name comes from the task or the issue title and ends in a short random id, such as
fix-login-3acea3. The pencil edits it. The line below shows the branch it creates,
offsite/fix-login-3acea3; the prefix is set per repository in the
setup.
The Base is the branch the worktree starts from. Default branch follows
origin/HEAD, then origin/main or origin/master, then a local main or master.
Offsite fetches the base right before it creates the worktree, so the agent starts on
what the remote has now. A repository without a default branch asks you to choose one.
The folder lands under ~/.offsite-worktrees, in a folder per repository.
The agent
Section titled “The agent”In Task and GitHub mode you pick the agent (Claude, Codex or Grok), its model and effort. YOLO lets it work without permission prompts.
The task becomes the agent’s first prompt. It also gets a short brief with the rules of a worktree: work only in this folder and on this branch, start apps through Offsite on the worktree’s ports, and leave commits, pushes and merges to you unless the task asks for them.
When the repository has a setup, the agent starts after it succeeds. When a long setup ends, a notification titled Setup done in fix-login-3acea3 says that the agent starts now, so you can work elsewhere meanwhile.
From an issue or a pull request
Section titled “From an issue or a pull request”GitHub mode lists the repository’s open issues and pull requests through the GitHub CLI. An issue gives the worktree its name and its task: the agent reads the issue’s title and text along with your own words. A pull request checks out its branch, ready for a review or a follow-up.
In Task mode, a task that starts with #123 or contains a GitHub issue or pull
request URL is linked the same way. The dialog says Linked to #123, or Checks out
the pull request’s branch for a pull request URL.
A linked worktree carries the number on its card. When it opens a pull request, the
description ends in Fixes #123 for an issue or Refs #123 for a pull request, so
GitHub closes the issue with the merge.
Ask an agent to create one
Section titled “Ask an agent to create one”An agent session in the repository can create a worktree for you. Say “create a worktree
and implement the search filter” and the agent calls its worktree_create tool: the same
worktree you would get from the dialog, with its board, setup, ports and a new agent that
starts on the task. The agent’s CLI asks for your OK first unless the session runs in
YOLO, and the agent carries on with its own work afterwards.
Agents that steer Offsite has the details.
Worktrees made elsewhere
Section titled “Worktrees made elsewhere”A worktree you create with git worktree add, in GitHub Desktop or through an agent’s own
worktree command shows in the column as External worktree. Its … menu offers:
- Add worktree to this workspace (or a click on the card): it becomes one of Offsite’s worktrees, with its own board and port window, and its Run buttons follow the repository’s setup. The folder stays where it is and keeps what it has; the board opens with the Git and Files cards.
- Hide: the card leaves the column. Host Settings › Worktrees lists hidden worktrees with Unhide.
A worktree you once opened as a workspace of its own stands in the column under its own name, and Manage here in its … menu makes it one of Offsite’s worktrees.
The first time in a repository
Section titled “The first time in a repository”The first + in a repository checks that there is something to branch from. A folder without git, or a repository without a commit, gets a short note with the way through the Git card.
A repository without a worktree setup gets one question: Set it up opens the Worktree Setup, Later creates plain checkouts for now. The New Worktree dialog keeps a line at its foot with Setup once…, Set it up now… or Edit setup….