Your first worktree
A worktree is a second checkout of your repository on its own branch. Give each task one, and each agent works in its own files without stepping on the others.
Create the worktree
Section titled “Create the worktree”Press ⌘⇧N, right-click the project’s name and choose New Worktree, or click New worktree at the foot of the sidebar. The Create worktree dialog asks for:
- Project, when you open it from the foot of the sidebar with more than one project.
- Name: the branch to create, such as
fix-flaky-poll. The branch must not exist yet. - Agent: which agent starts in the worktree, or No agent (blank terminal). It defaults to the project’s preferred agent, then to your global default.
- Economy: how terse the agent should be. It starts at Off. See Economy.
Tab moves between the fields, ↵ creates, and Esc closes.
ket fetches the remote first, then cuts the branch from the project’s base branch. The dialog shows “Fetching the remote and creating the worktree…” while it works. When it’s done, ket selects the new worktree and opens a terminal in it.
Start the agent
Section titled “Start the agent”If you picked an agent, ket starts it in the worktree’s terminal. It types the agent’s command at your login shell’s prompt, exactly as you would, so your aliases and version managers still apply. The tab is named after the agent. Give it the task as you normally would.
To add another session later, open the + menu on the tab bar and pick an agent, or press ⌘⌥ and the agent’s position (1–9).
When you come back to a worktree, ket resumes the agent’s last session in it.
Watch its status
Section titled “Watch its status”Each row in the sidebar carries a state word:
- running: the agent is thinking or running a tool.
- waiting: the agent needs you, usually to approve a tool.
- No word: the agent is idle or finished.
The header adds up running and waiting across every project. When a worktree in another project needs you, the count and the row’s pulsing dot tell you. The sidebar’s Waiting filter lists only those rows.
Review and merge
Section titled “Review and merge”Open the Git view with ⌘⇧G to see what changed. Click a file to open its diff.
When the work is ready, press ⌘⇧M, or click the row’s merge button. ket lists the files it will commit, commits them, and merges the branch into the base branch in the primary checkout. A toast confirms the merge, and the worktree stays. When you’re finished with it, choose Delete from its row menu.
Git, diffs and merging covers each step and what stops a merge.