Engineering demo

Work on parallel features
using coding agents

One engineer. A fleet of agents. Every feature in its own isolated world — folder, branch, and ports.

npm i -g @rousan/mx mx.rousanali.com open source · MIT

The reality

You're never working on just one thing

feature-a
agent working
feature-b
waiting on you
feature-c · urgent
waiting on you
and every switch runs the meter
git stash
checkout + branch
reinstall deps
port clash
rebuild context

Three things in flight, but you can only stand in one checkout at a time — so two of them sit idle, and each hop back costs you ~20 minutes.

The obvious answer

“Can't I just use subagents, or a tab per feature?”

One session, many subagents
agent session
subsubsub
all share one checkout
A terminal tab per feature
feature-a feature-b feature-c +

A reasonable instinct. It even works — for about a day.

Where it cracks

Three cracks show up fast

01 · Ports
repo-a
:3000
repo-a
:3000
Two dev servers, one port. Address already in use — you juggle port numbers by hand.
02 · Hydration
wt/repo-a (fresh)
.env missing
node_modules/ missing
db seed missing
A raw worktree is empty. Copy env, install, seed — by hand, every single time.
03 · Multi-repo
one feature ↓
repo-a ⋮ repo-b
session = one repo
A feature spans two repos, but a session lives in one checkout — the second repo is out of reach.

And it gets worse over time: no lifecycle to archive or recover a feature, no shared memory between them, and a pile of tabs, folders, and branches you track in your head.

The answer

Meet mx

The one tool that makes all three cracks disappear.

What is mx

The whole system in one picture

pristine repos · cloned once, read-only
repo-a repo-b repo-c
context registry
shared memoryfindings · conventions · runbooks
read by every agent
worktrees fork from repos · every agent shares the context
feature-a1 agent
repo-a:3001
repo-b:3002
feature-b1 agent
repo-b:3003
feature-c1 agent
repo-a:3007
repo-c:3008
feature-d1 agent
repo-c:3009
feature-e1 agent
repo-a:3011
repo-b:3012

Repos up top (cloned once, read-only), a context registry in the corner (shared memory every agent reads), and one work per feature — each with its own agent and a worktree + port per repo it touches.

Mission control

One view of the whole fleet

mx mission-control · localhost:7777 live
In progress
feature-aactive
repo-a:3001
repo-b:3002
feature-cactive
repo-a:3007
repo-c:3008
In review
feature-breview
repo-b:3003
PR review
feature-dwaiting
repo-c:3009
feature-ewaiting
repo-a:3011
repo-b:3012

Every feature and its ports, grouped by stage — one place to see the whole fleet: what's in progress, in review, and up for PR. Nothing lost in a forgotten tab.

mx mission-control

See the whole runtime, live

mx mission-control dashboard: each work with its services, ports, and live localhost URLs

mx mission-control starts a local, read-only web dashboard — every work with its services, allocated ports, and live localhost URLs, plus repo and work health, streamed live.

Live · my setup

How I actually run mx

  • One fullscreen macOS Space per feature — terminal + editor split side by side.
  • Coding agent in the terminal (auto mode); dev server & git in another tab.
  • Three-finger swipe between features; Mission Control for the whole board.
  • Grouped by stage with mx divider — in progress, in review, shipped.

Let me switch over and show you my real setup — then we'll break down each piece.

How it's organized

Four words, and you've got it

Runtime~/mx — one folder for everything
Repos · cloned once, read-only
repo-a repo-b repo-c repo-d
Works · one per feature — each can span several repos
feature-a
wt/repo-a
feature-a · :3001
wt/repo-b
feature-a · :3002
feature-b
wt/repo-b
feature-b · :3003
wt/repo-c
feature-b · :3004

Runtime holds it all · Repo is a clone · Work is a feature · Worktree (wt/<repo>) is a checkout you code in — a work can have one per repo.

On disk

The whole runtime is one folder

~/mx/ the runtime — one folder ├── repos/ pristine clones (read-only) │ └── repo-a/git · repo-b/git · repo-c/git · repo-d/git ├── works/ one folder per feature │ ├── feature-a/ │ │ ├── wt/repo-a · wt/repo-b a worktree per repo │ │ ├── sessions/ session summaries │ │ └── work.json manifest (mx-owned) │ └── feature-b/ · feature-c/ · feature-d/ …more ├── context/ shared memory · institutional knowledge │ ├── INDEX.json the searchable index │ ├── auth/tokens.md how the system works │ ├── conventions/style.md team rules & conventions │ └── runbooks/deploy.md step-by-step runbooks ├── hooks/ lifecycle hooks │ ├── post-worktree-create hydrate: cp .env, install, seed │ └── session-prompt · work-health · repo-fetch … ├── bin/ dcs · lcs runtime-wide CLI helpers └── files/ creds.env · clusters.json shared operational values

mx owns the structure — work.json, the editor workspace, and ports are written only through mx commands. repos/ stay read-only; everything you build lives in works/<feature>/wt/.

Parallel agents

One agent per checkout → a fleet in parallel

you
feature-aagent · working
feature-bagent · working
feature-cagent · working

Each agent lives in its own worktree, branch, and ports — so a fleet works at once, and none of them step on each other.

Feature · worktrees

Many working copies, one clone

repos/repo-a/git
pristine clone · read-only
wt/repo-afeature-a
wt/repo-afeature-b
wt/repo-afeature-c

git worktrees let many branches be checked out at once, in separate folders, sharing one .git object store — full isolation with no duplicated repo on disk. mx creates and tracks them for you (mx work new / worktree add).

Feature · repos

One feature, many repos — one agent covers all

one
agent
works across both repos
→
1 work · feature-a
wt/repo-abranch: feature-a
wt/repo-bbranch: feature-a

The one-session-one-repo wall, gone. A work groups a worktree per repo under one feature, so a single agent session edits across all of them — the change spanning repo-a + repo-b that a per-repo tab simply can't make together.

Feature · ports

Run the same app many times, side by side

localhost:3002up
repo-a · feature-a
localhost:3004up
repo-a · feature-b
localhost:3006up
repo-a · feature-c

The port clash, gone. mx allocates each feature its own ports, unique across the whole runtime — so the very same app (repo-a) runs three times at once, one per feature, each with its own live URL. mx work port set hands out a free one; the ports board shows who owns what.

Feature · hooks

A fresh worktree, ready to run

new worktree
mx work new / worktree add
cp .envconfig in place
pnpm installdeps ready
seed the dbdata ready
allocate portsno clashes

The hand-hydration, automated. The moment a worktree exists, mx fires the post-worktree-create hook — you decide what “ready” means (copy env, install, seed, …), in any language. It's one hub of lifecycle hooks: worktree create/remove, work archive/unarchive, repo fetch, health, and session-prompt.

Feature · context

Shared memory across every feature

context/
INDEX.json · 40 entries
auth/tokens
conventions/code-style
runbooks/deploy
…
feature-aagent reads context
feature-bagent reads context
feature-cagent reads context

The shared memory you didn't have. A runtime-wide registry of findings, decisions, conventions, and runbooks — indexed in INDEX.json. Every feature's agent reads the same institutional memory, so a hard-won discovery in one feature isn't re-learned in the next.

What one feature looks like

One feature, one Space

A feature Space: a coding agent in auto mode on the left, the editor on the right

A real feature Space: the coding agent in auto mode (left) working one feature across two repos, the editor beside it. Terminal left, editor right — one fullscreen macOS Space per feature.

Your board

One Space per feature, grouped by stage

The clutter, organized. Every feature is its own macOS Space, grouped by stage with mx divider — so you always know what's in progress, in review, and shipped. Swipe to switch; nothing is ever torn down.

Memory & lifecycle

Pause a feature, pick it up later

Active
Worktrees, ports, an agent session — and sessions/*.md notes as you go.
→mx work archive
Archived
Worktrees & ports freed. Branches and session summaries kept — recoverable.
→mx work unarchive
Back to work
Worktrees re-created; continue right where you left off.

The lifecycle you were missing. Every work keeps session summaries (sessions/*.md) — a distilled record of each session, so you or a fresh agent can resume cold. mx work archive frees the ports and worktrees but keeps the branches and notes; mx work unarchive brings it all back.

The payoff

Serial → parallel

The old wayfeatures one after another
feature-a
feature-b
feature-c
feature-d
With mxagents in parallel
startdone in ~1/4 the wall-clock

More shipped per engineer — parallel instead of serial, and it compounds as agents do more of the typing.

Try it

Two commands in

1
$npm i -g @rousan/mx
2
$mx init

Then mx repo add your repos and mx work new your first feature. Full guide, mental model, and command reference: mx.rousanali.com

Give every feature its own desk.

Questions? Let's run one live.

npm i -g @rousan/mx mx.rousanali.com github.com/rousan/mx
mx
mx ← → or space · F fullscreen · T theme 1 / 23