Coding agents
mx was designed for the coding-agent era. A coding agent (Claude Code, Cursor, and friends) works in one checkout at a time — so to run several agents in parallel, you need several isolated checkouts. That's exactly what mx gives you: one worktree, branch, ports, and agent session per feature, all isolated, none stepping on each other.
One agent per feature
Because each work is a fully isolated environment, you can run a separate agent session in each — a whole fleet making progress at once:
search-filters— an agent working acrosswt/web+wt/apidark-mode— an agent inwt/webflaky-tests— an agent inwt/api
Each has its own branch and its own ports, so their dev servers and changes never collide.
Open a work with its session
Each work is a tmux session named mx/<work>, with the agent already running in it. Enter a work with attach (this terminal) or open (a new window):
mx work -n search-filters attach
# open in a new terminal window instead:
mx work -n search-filters open
# or create-and-open in one step:
mx work new search-filters web api -oEither way, mx builds the session if it doesn't exist yet — a main window with the Claude Code session on the left and nvim on the right, plus a run window of shells. The agent session is keyed to the work, so you always continue the same conversation:
- First time → mx creates it, seeded by the
session-prompthook (or--prompt). - Re-attach → mx resumes the same session by its pinned id.
See The tmux workflow for the full model — the default layout, self-healing, and customizing it.
Seed the agent with session-prompt
The session-prompt hook runs when mx creates a work's session (not on resume). Its stdout becomes the session's initial prompt — a great place to hand the agent the feature's context automatically:
#!/usr/bin/env bash
# <runtime>/hooks/session-prompt (cwd = the work folder)
echo "You are working on the feature '$MX_WORK'."
echo "Read ../../context/INDEX.json for shared conventions before starting."Override it for a single session with mx work attach --prompt "…" (or open --prompt).
Shared memory across agents
Every agent, in every work, can read the runtime's context registry — a shared store of conventions, decisions, and runbooks. A convention set in one feature is available to every other feature's agent, instead of being trapped in one session's history.
A workflow that works well
One common setup, feature by feature:
- One tmux session per feature (
mx work attach) — the agent andnvimsplit in themainwindow, dev servers in therunwindow. - Switch features by detaching (tmux prefix +
d) andattach-ing another; each session keeps running in the background. - Keep a terminal window per active feature if you like, and group them into macOS Spaces — then label the Spaces by stage with
mx divider(in progress, in review, shipped). - On merge: write a session summary, then
mx work archive(which also tears down the tmux session).
The workflow is flexible — this is just one shape that fits the tool well.
Related
- The tmux workflow — the session, layout, and
attach/open. - Context registry — shared memory every agent reads.
- Hooks & hydration — the
session-promptandwork-sessionhooks. - Mission control — dividers and the fleet view.