Getting started
This guide takes you from zero to a running parallel feature in a few minutes. You'll install mx, create a runtime, add a repo, and spin up your first work.
Prerequisites
- Node.js 18+ and git.
- A repo (or two) you want to work on. mx works with any git repo — local or remote.
- For the tmux workflow (opening a work with its agent and editor), you'll also want tmux, neovim, and the Claude Code CLI — see Prerequisites for the install commands and
mx doctor. mx supports macOS and Linux.
Install
mx ships as a single global CLI on npm:
npm i -g @rousan/mxThis gives you the mx command. Check it:
mx versionCreate a runtime
A runtime is one folder that holds everything — your cloned repos, your per-feature works, shared context, and configuration. Create one with mx init:
mx initBy default the runtime lives at ~/mx. You can point mx elsewhere with the $MX_RUNTIME environment variable or the --runtime flag; see Core concepts for details.
Add a repo
Repos are cloned once into the runtime as read-only reference clones. Add one:
mx repo add git@github.com:your-org/your-app.gitYou can add as many as you like — a single feature can span several of them. List what's there:
mx repo lsTIP
mx never lets you edit the pristine clone directly. All your work happens in worktrees forked from it — that's what keeps many features isolated while sharing one clone on disk.
Create your first work
A work is one feature. Create a work and its initial worktree in a single command:
mx work new add-search your-appThis creates:
- a work folder for
add-search, - a git worktree of
your-appon a new branch (add-searchby default), forked from the pristine clone, - an editor workspace file you can open directly.
Want the feature to span multiple repos? List them all:
mx work new add-search web apiEach repo gets its own worktree under the one work, so a single agent session can edit across all of them.
Open your work
Now step into the work. mx work attach builds the work's tmux session — the coding agent and nvim side by side, plus a window of shells — and attaches your terminal to it:
mx work -n add-search attach
# or open it in a new terminal window:
mx work -n add-search open # alias: -oThe agent session is keyed to the work, so re-attaching later always resumes the same conversation. Detach (your tmux prefix + d) to leave everything running in the background. Prefer VS Code? mx also generates a .code-workspace file you can open directly. See The tmux workflow for the full picture.
Allocate a port
If your app runs a dev server, give it a port that's guaranteed unique across every work in the runtime:
mx work -n add-search port set your-app webmx records the port; you then wire it into the repo's own config (.env, PORT=, etc.). Because every feature gets its own port, you can run the same app for several features at the same time without clashes.
See everything
Get a full picture of the work — its repos, branches, and ports:
mx work -n add-search info --porcelainOr launch the live dashboard for the whole runtime:
mx mission-control # alias: mx mcPause and resume
Done with a feature for now? Archive it to free its ports and worktrees while keeping the branches and any notes:
mx work -n add-search archiveWhen you're ready to pick it back up:
mx work -n add-search unarchiveNext steps
- Tutorial — the full end-to-end story: two features in parallel across two repos, then archive and resume.
- Core concepts — the four words (runtime, repo, work, worktree) the whole tool is built on, and the one rule that governs everything.
- Guides — go deep on any feature: the tmux workflow, ports, hooks & hydration, the context registry, mission control, the archive/resume lifecycle, and coding agents.