Works & worktrees
A work is one feature. A worktree is a git worktree inside that work — a real checkout of a repo on a feature branch, living at works/<feature>/wt/<name>, where you and your coding agent actually write code.
A work can hold worktrees of several repos (a feature spanning a frontend and a backend), and even several worktrees of the same repo (two branches of one repo side by side).
mx owns the state
mx is the single owner of the work manifest (work.json) and the editor workspace. You never hand-edit those files, and you never run raw git worktree — always go through mx commands, so the manifest can't drift from what's on disk.
Create a work
The simplest form creates the work and its first worktree at once:
mx work new search-filters webList repos to add a worktree per repo the feature touches:
mx work new search-filters web apiPer repo you can pin the branch and where it forks from with <repo>:<branch>:<base>:
mx work new search-filters web:search-filters:main api:search-filters:develop- branch defaults to
--branch, then the work name. - base (where to fork from) defaults to
--base, then the clone's currentHEAD. A bare branch name resolves to that local branch ororigin/<name>.
Add -o / --open to open the work immediately (see Coding agents).
Add a worktree to an existing work
If a feature grows to touch another repo:
mx work -n search-filters worktree add apiGive a distinct name to hold a second worktree of the same repo:
mx work -n search-filters worktree add web web-hotfix --branch hotfixThe name (web-hotfix here) is the wt/<name> directory and the selector you'll use later. It defaults to the repo name.
Creating a worktree runs a hook
The moment a worktree is created, mx fires the post-worktree-create hook so it can be hydrated (copy .env, install deps, seed data). See Hooks & hydration.
List worktrees
mx work -n search-filters worktree ls
mx work -n search-filters info --porcelain # full manifest as JSONSwitch a worktree to another branch
mx never runs git checkout for you. Switch branches the normal way inside the worktree, then tell mx so the manifest stays truthful:
cd "$(mx work -n search-filters path)/wt/web"
git checkout other-branch
mx work -n search-filters worktree set-branch web # re-records the live branchPass an optional branch name as a guard — it must match what the worktree is actually on, else mx errors (BRANCH_MISMATCH).
Remove a worktree
mx work -n search-filters worktree rm web-hotfixRefuses if the worktree has uncommitted changes.
Tear down a work
When a feature is fully merged and you want it gone:
mx work -n search-filters destroyThis removes the worktrees and the work folder but keeps the branches. It refuses if any worktree has uncommitted changes. To pause a feature instead of destroying it, use archive.
Related
- Ports — give each worktree's services a port.
- Archive & resume — park a work and bring it back.
- Core concepts — the runtime / repo / work / worktree model.