Groups and worktrees

A group binds sessions to a root folder on the environment's host. Its terminals start there, and the file tree and git state come from there. An environment can hold groups from different repositories, and several worktrees of the same repository side by side.

A group always has at least one session. When you remove a group, its terminals close and its sessions go too.

WorktreesCopy Anchor Link

A worktree is a separate git checkout of the group's repository on its own branch, opened as a new group, so an agent can work without touching other checkouts. Start one for an agent that should not step on the others.

Worktrees are sibling folders next to the repository:

my-app/                      the group's repository
my-app.worktrees/
  api/                       a worktree on its own branch, its own group
  ui/                        another worktree, another group

A lead can start a Worker in a new worktree with krad-ade-agents spawn --worktree <name>. See Lead and Workers.

Before a worktree is removed, the app closes the terminals of its group, since Windows cannot delete a folder that a running process still uses. If the worktree has uncommitted changes, git declines to remove it, and the app shows that message rather than forcing the removal.

Git through the git CLICopy Anchor Link

The app runs the git program for all git work, which means your own git config, credentials and hooks are used, on every platform alike. It reads each group's git state every few seconds, so a change made in a terminal can take a moment to show.

Git changesCopy Anchor Link

The side panel holds the group's git changes beside the file tree:

• Staged changes. Mark the changes that go into the next commit. A commit with nothing staged takes every change.
• Discard. Throw away a file's uncommitted changes so it matches the last commit; a file git does not track yet is deleted. A single block of changed lines can be reverted the same way from its diff.
• History. The commits of the group's branch and its upstream, newest first, drawn as a graph of lanes. A commit opens to list the files it changed, each shown as a diff against its first parent.
• Stashes. Set uncommitted changes aside to clean the working tree, and bring them back later.

Branch switcherCopy Anchor Link

The branch switcher is the searchable list of the group's worktrees, local branches and remote branches. Open it from the environment pill or from the branch in the git changes.

• Picking a worktree opens its group.
• Picking a local branch checks it out in the selected group.
• Picking a remote branch checks it out through a new local branch that tracks it.

Groups on remote hostsCopy Anchor Link

In an environment on a remote host, groups, worktrees and git all live on that host. Adding a group or a worktree there uses an in-app folder browser, because the system's folder picker only sees this computer.