Projects and worktrees

Where a chat works

A project in the sidebar can have rows under it. A chat runs in whichever row you start it from:

• The project folder itself, when no row is selected.
• A folder inside the project, added from the project's menu with New folder...
• A worktree: a separate copy of the code on its own Git branch, added from the project's menu with New worktree...

Offrun does not make a worktree for each chat on its own. A new chat runs in the row you selected, and every chat in the same folder edits the same files. Give agents separate worktrees when they work on one repository at the same time.

Create a worktree

1. Right-click the project in the sidebar, or press its ... button, then choose New worktree...
2. Type a name for the work, such as Fix login bug.
3. Leave Create a new git work tree ticked and press Create.

Offrun runs git worktree add for you. The branch is the name in lowercase with spaces turned into dashes, so Fix login bug becomes fix-login-bug, in .worktrees/fix-login-bug inside the project. If the name is taken, Offrun adds -2 and tells you. If a local branch with that name already exists and is not checked out anywhere, the worktree uses it instead of making a new one.

The worktree branches from the commit the project folder is on. Anything uncommitted in the project folder is not in it, so commit first if the agent needs it.

A worktree needs a Git repository with at least one commit. Without Git, New worktree... is greyed out and marked Needs Git. In a repository with no commits yet, make the first commit, then try again.

If the project folder holds several repositories rather than being one, Offrun makes one worktree per repository, all on the same branch, under .worktrees/fix-login-bug/. Files at the top of the project folder are linked in rather than copied, so edits to them are not kept apart.

Run chats in it

Select the worktree's row and press + beside it, or ⌘T. Every chat started there shares that worktree. For two agents that must not touch each other's files, make a worktree for each.

To move a chat that already exists, open its menu and choose Move to, or drag it onto another row. Offrun asks first when the move crosses into or out of a worktree, because the code does not move with the chat: what it already changed stays where it was made. Its next turn runs in the new place.

Rename on a worktree row changes only the name Offrun shows. The branch and folder keep theirs.

Keeping Offrun out of your diffs

Offrun adds .worktrees/ and .offrun/ to the repository's local .git/info/exclude, which Git reads like a .gitignore that is never committed. Your own .gitignore is left alone.

Finish with a worktree

Offrun has no merge button, and nothing merges on its own. When the work is done, review it, commit it in the worktree, and merge the branch with your usual tools:

git -C .worktrees/fix-login-bug status
          git -C .worktrees/fix-login-bug add -p
          git -C .worktrees/fix-login-bug commit -m "Fix login bug"
          git diff main...fix-login-bug
          git merge fix-login-bug

Then remove the worktree. Git keeps the branch until you delete it:

git worktree remove .worktrees/fix-login-bug
          git branch -d fix-login-bug

Deleting a worktree row in Offrun

Choose Delete from the worktree row's menu. It deletes the row and all its chats. By default the folder and its files are kept; tick Move the folder to the Trash and type delete to remove them too. Offrun will not delete a row while one of its agents, jobs or terminals is running.

Deleting runs no Git command, and Offrun does not check for uncommitted work first. Commit or copy anything you want before you trash the folder. Afterwards the branch is still there, and Git still lists the worktree until you run git worktree prune.