Skip to main content
Running two agents on the same repository at once means they fight over the working tree. A git worktree is the fix, and tty7 makes it a single dialog: create the checkout, make it runnable, and start the agent in it.

​
Creating one

New Worktree Tab… — in Search Everywhere, the tab’s right-click menu, and the application menu — asks: Each field opens on a suggestion you can accept or type straight over.
Creating a worktree

The New Worktree Tab dialog, every field pre-filled

Confirm and tty7 creates the worktree, copies in what .worktreeinclude asks for, opens a tab there, and runs .tty7/setup followed by the agent. The sidebar files it under the same repository group as its parent, on its own branch. The new branch does not track origin/main: its first git push -u goes to a branch of its own name.

​
Files a checkout needs: .worktreeinclude

A fresh checkout has none of your gitignored files — no .env, no local settings. List the ones it needs in .worktreeinclude at the repository root, in gitignore syntax:
A path is copied only if it matches and git ignores it. Copies are copy-on-write where the filesystem supports it (APFS on macOS, btrfs and XFS on Linux): a copied directory costs no disk until one side changes it. Nothing is symlinked, because two checkouts sharing one dependency tree break each other the moment their lockfiles disagree. On a remote machine the files go over the connection, up to 64 MB in total — enough for configuration, not for node_modules.

​
Making it runnable: .tty7/setup

Commit an executable at .tty7/setup — any language, with a shebang — and every new worktree runs it in its first tab, before the agent. Install dependencies there, rather than copying them:
TTY7_PORT comes from the worktree’s path, so a dev server started there does not collide with its siblings, and the same worktree always gets the same ports. The setup and the agent are chained with &&: if setup fails, the agent does not start and the error stays on screen. The script is code from the repository, so tty7 asks before running it the first time, and again whenever its content changes. Without a setup script, the dialog suggests one based on your lockfile (pnpm install, uv sync, …). Setup runs on macOS and Linux; Windows worktrees skip it.

​
Where they go

Worktrees land inside the repository, under:
The directory is listed in .git/info/exclude, so it never shows up in git status, and .tty7/setup next to it stays committable.

​
Removing one

Closing a worktree tab offers to remove the worktree with it:
  • Clean tree — Remove Worktree or Keep.
  • Dirty tree — the dialog says so, and removing requires the explicit Discard Changes & Remove.
Before anything is deleted, the checkout’s state — uncommitted and untracked files included — is saved under refs/tty7/trash/<name>. Even a discarded change can come back:
The branch is deleted only if it is merged; otherwise tty7 says it kept it. Keep leaves the worktree on disk, and tty7 worktree ls finds it later.

​
From the command line

See the CLI reference.
Pair this with agent sessions: a worktree per agent means two Claude Codes can work on the same repository without stepping on each other’s files.