Skip to content

Hooks & hydration ​

A raw git worktree is an empty checkout — no .env, no installed dependencies, no seeded database. Hooks let mx make a fresh worktree ready to run automatically, and hook into other lifecycle moments too.

A hook is just an executable mx runs at a lifecycle moment. They all live in one place — <runtime>/hooks/ — with one file per event, named exactly for the event. mx stamps a documented no-op for each on mx init; you edit them in place.

Hydration: the post-worktree-create hook ​

The most useful hook. It fires right after a worktree is created, with the new worktree as the working directory — so it's where you copy env files, install deps, seed data, and allocate ports.

bash
#!/usr/bin/env bash
# <runtime>/hooks/post-worktree-create
set -euo pipefail

# Hooks are runtime-wide, so branch on context via MX_* env vars.
case "$MX_REPO" in
  web|api)
    cp ~/secrets/"$MX_REPO".env .env   # config in place
    pnpm install                       # deps ready
    ;;
esac

Now every new worktree of web or api is ready to run the moment it exists.

Branch on context ​

A hook fires for every repo and work, so you dispatch inside the script using MX_* environment variables — always $MX_EVENT and $MX_RUNTIME, plus event-specific ones like $MX_WORK, $MX_REPO, $MX_BRANCH, $MX_BASE, $MX_WORKTREE_PATH, $MX_WORK_PATH. Each shipped hook's header comment documents exactly which variables it receives.

Write them in any language — bash, Node, Python — just set the shebang and keep the file executable. Delete a hook file to disable that event.

Every event ​

HookFiresNon-zero exit
pre-worktree-createbefore a worktree is createdaborts creation
post-worktree-createafter — the hydrate stepwarning (worktree kept)
pre/post-worktree-removearound worktree removalpre aborts; post warns
pre/post-work-archivearound mx work archivepre aborts; post warns
pre/post-work-unarchivearound mx work unarchivepre aborts; post warns
pre/post-repo-fetcharound mx repo fetchpre aborts; post warns
repo-healthduring mx repo healthstdout captured into the health report
work-healthduring mx work healthstdout captured into the health report
session-promptwhen mx work attach / open creates a work's agent sessionstdout becomes the session's initial prompt
work-sessionafter mx builds a work's tmux sessionwarning (session kept)

pre-* hooks are veto points — a non-zero exit aborts the operation before anything is mutated. post-* hooks run after success; a non-zero exit is only a warning.

Health hooks ​

repo-health and work-health augment mx repo health / mx work health. Follow the silent-when-healthy convention: print nothing (or a bare ok) when things are fine, print the problem when they're not.

bash
#!/usr/bin/env bash
# <runtime>/hooks/work-health   (cwd = the work folder)
[ -f wt/web/.env ] || echo "web worktree is missing its .env"

The session-prompt hook ​

When mx work attach (or open) creates a work's coding-agent session, this hook's stdout becomes the session's initial prompt — a great place to seed the agent with the feature's ticket, links, or task. It fires only on create, never on resume, and --prompt <text> overrides it. See Coding agents.

The work-session hook ​

mx builds every work a tmux session with a default layout — a main window (Claude + nvim) and a run window of shells. The work-session hook fires after mx has built that session, with the work folder as the working directory, so you can reshape the layout: add a window per repo worktree, start a dev server, swap the editor, rename panes.

Its environment adds two variables on top of the usual MX_WORK / MX_WORK_PATH:

  • MX_TMUX_SESSION — the tmux session name (mx/<work>), i.e. your tmux target.
  • MX_CLAUDE_SESSION_ID — the resumed session id (empty on a fresh create).

It's post-style — a non-zero exit only warns, and the session is kept. Delete the file to keep mx's default layout.

bash
#!/usr/bin/env bash
# <runtime>/hooks/work-session   (cwd = the work folder)
set -euo pipefail

# Add one dedicated window per worktree under wt/.
for dir in wt/*/; do
  name="$(basename "$dir")"
  tmux new-window -t "$MX_TMUX_SESSION" -n "$name" -c "$MX_WORK_PATH/$dir"
done

session-prompt vs work-session

session-prompt seeds the first agent prompt (create-only). work-session shapes the tmux layout every time the session is built. See The tmux workflow.

Released under the MIT License.