One branch, one worktree, at a path derived from git

The container is the primary checkout's sibling named with -wt, a branch's worktree is the branch name under it with its hierarchy kept, both derived from git identity and registered nowhere; a pre-commit guard refuses a feature branch committed from anywhere else, and migration moves a misplaced worktree with its uncommitted work, fingerprinted before and after.

A branch's worktree is where git says it is, never where somebody chose to put it, and a misplaced one is a diagnostic with a remedy rather than a mystery.

status: stable
exposed through: cli

api

mcp

cockpit

docs
area: coordination; work-tracking

What it does

Given the repository and a branch name there is exactly one path, and every surface derives it the same way: majordomus worktree create <branch> makes the branch from the trunk and the worktree at that path, worktree path prints it for a shell to cd into, worktree alone says where the current session is and whether that is where it belongs, and worktree migrate brings a misplaced worktree home with its modified, staged and untracked files intact. Nothing registers a path: git's own common directory, its worktree list and its refs are the registry.

The pre-commit hook asks worktree guard and refuses a feature branch committed from the primary checkout or from a worktree that is not the branch's own. The topology is one capability module, so the same typed answer — every worktree with its standing, every diagnostic with its code and remedy — is on the command line, over MCP and HTTP, and on the Cockpit's worktrees page.

What it does not do

It never deletes a branch, never overwrites a destination that exists, and never moves a detached worktree or a session's scratch checkout unless asked. It does not decide what a branch is for; the issue a branch names is read from its name when it names one.

The capabilities behind it

The capability modules of the executable this feature names, each with the capabilities it composes. The command line, the HTTP route, the MCP tool and the reference beside every row are projections of one declaration, not four registrations.

Worktree topology worktree behaviorally verified

Where every linked git worktree of this repository belongs and where each one is. The container is the primary checkout's sibling named with `-wt`, the path under it is the branch name with its hierarchy kept, and both are derived from git's own identity — the common directory, the registered worktrees, the branches — never from a registry, a configuration or the current directory. A worktree somewhere else is a typed diagnostic with a remedy; the migration that repairs it is a command-line operation of the same service.

One branch: where its worktree belongs and what is there query

$ majordomus worktree inspectGET /api/v1/worktrees/inspectmajordomus_worktree_inspect
What it would take to bring every worktree home query

$ majordomus worktree migrateGET /api/v1/worktrees/migrationmajordomus_worktree_migration_plan
Where this is, and whether that is where it belongs query

$ majordomus worktree statusGET /api/v1/worktrees/statusmajordomus_worktree_status
The whole topology query

$ majordomus worktree topologyGET /api/v1/worktreesmajordomus_worktrees

apps/majordomus-cli/src/capability/builtin/worktree.rs

What it answers

Operational moments from the Why catalogue that name one of this feature's mechanisms. Nothing here was assigned: a moment appears because it names a rule, a command, a capability or a claim this feature also names.

The rules that hold it

blockingA branch's worktree is at <repo>-wt/<branch>, derived from git, never registeredproject.worktree-topology
blockingNothing this repository commits names a path of the machine it was written onproject.no-machine-paths