Workspaces and git worktrees in Hive

How Hive groups sessions into spaces by repository, and gives an agent its own git worktree and branch, with the rules that keep your work safe.

Workspaces (spaces)

Every session belongs to a workspace, shown as a space in the sidebar. Hive picks it from the session's directory: inside a git repository it is the repository (worktrees included, so an agent in a worktree stays in its repository's space); elsewhere it is the folder. Terminals move with you when you cd; see spaces follow your terminals.

Workspaces are remembered across daemon restarts. Manage them with Ctrl+Space w, right-click on a space, or:

hive workspace list
hive workspace add ~/src/api -n api     # a space without opening a terminal
hive workspace rename api backend
hive workspace rm backend               # only when it has no sessions; nothing on disk changes

Why worktrees

Two agents in the same checkout edit the same files, and one's half-finished change breaks the other's tests. Hive warns with ! beside agents that share a directory. A git worktree gives an agent its own checkout of the repository on its own branch: separate files, shared history. You review and merge its branch when it is done.

Starting an agent in a worktree

`hive new codex -w`	Codex in a new worktree on branch `hive/codex-<id>`
`hive new claude -b fix/login`	On branch `fix/login`, created from the current HEAD if missing
`Ctrl+Space` `C`	A terminal in a new worktree (`hive/shell-<id>`); start any agent there
`Ctrl+Space` `A`, then `w`	Pick an agent and give it a worktree

Worktrees go in ~/.local/share/hive/worktrees ($XDG_DATA_HOME), or [worktrees] dir. The sidebar marks those sessions wt with their branch.

Cleaning up

When you terminate a session in a clean worktree (Ctrl+Space x), Hive offers w to remove the worktree too. From the command line:

hive worktree list                 # branch, clean or modified, path, sessions in it
hive worktree rm <path>            # remove a clean worktree
hive worktree rm <path> --force    # also discard uncommitted changes (asks first)

Safety rules

A worktree with uncommitted changes is never removed without --force and a confirmation.
A worktree a session is still running in is never removed.
Branches are never deleted. Merge or delete them with git when you are done.
Hive runs ordinary git worktree commands, so git worktree list and your other tools see the same thing.

More on the workflow in git worktrees for AI coding agents.