md and Switchboard

The md CLI runs the medallion dev loop — worktrees, services, tests, PR briefs — and Switchboard is the desktop app over the same engine.

Install with an agent

Paste this into Claude Code, or any coding agent, in a terminal on the Mac you want set up. It installs both halves, asks where things live instead of guessing, and hands back what it cannot do for you.

Copied
▶ Read it first 
Install the `md` CLI and the Switchboard desktop app for medallion local development on this Mac. Both, not one: the CLI runs the loop from a terminal, and the app is the view over it.

Repo: git@github.com:trymedallion/medallion-dev-cli

Do not guess anything about my machine. Before you start, ask me where my medallion product checkout is, and where I want the medallion-dev-cli clone to live. If a path I give you does not exist, ask again rather than picking one.

Steps, in order:

1. Apple Silicon is a hard requirement. `sysctl -n hw.optional.arm64` must print 1. Stop if it does not.

2. Homebrew. If neither /opt/homebrew/bin/brew nor /usr/local/bin/brew exists, stop and tell me to install it myself from https://brew.sh - its installer prompts for my sudo password, which you cannot answer. On Apple Silicon it must live at /opt/homebrew; a Homebrew under /usr/local is the Intel build and md cannot load its libraries.

3. uv. If it is not on PATH, install it with `curl -LsSf https://astral.sh/uv/install.sh | sh`. Any recent version is fine here; medallion pins a narrower range and `md setup` in step 7 installs that version itself.

4. Clone medallion-dev-cli to the path I gave you, then run `uv tool install --editable .` inside it. Editable is required: `md upgrade` and the desktop app both run from that working tree, not from a copy.

5. If `md config` does not already resolve my medallion checkout, point it there with `md config set main_repo <path>`.

6. Postgres. Run `md config show` and check whether anything answers on the `postgres_port` it reports (5432 unless it has been moved). If nothing does, stop and tell me to install Postgres.app from https://postgresapp.com, launch it, click Initialize, then turn on Preferences > Start at login so it survives a reboot. md never installs it, and `md setup` skips work until it is running. If a docker stack is already holding 5432, mention that `md setup` can move the native services to 5433/6380 so both run at once.

7. Run `md setup`. It brew-installs everything else: direnv, mprocs, watchman, node, yarn, libpq, libmagic, cairo, glib, pango, redis, and a matching Python. It is interactive and prompts per action, so ask me before you pass `--yes`.

8. Run `command md shell install zsh`, then append `eval "$(direnv hook zsh)"` to ~/.zshrc if it is not there already. This comes after step 7 because step 7 is what installs direnv.

9. Run `md doctor`. Every red row prints its own fix command. Work them, then re-run.

10. Run `gh auth status`. If gh is missing or unauthenticated, tell me: `md brief`, `md release`, `md babysit` and `md review` all reach GitHub through gh, and both repos are internal to trymedallion. Its answer decides which line you use in step 11.

11. Switchboard, the desktop app. Install it without asking me first - it is half of what I asked for, not an add-on. With gh authenticated: `md desktop install`. Without it: `curl -fsSL https://switchboard.medallion.md/install.sh | sh`, which needs no GitHub access at all. Either way, confirm with `md desktop status` and tell me that ⌘⇧M toggles the window.

12. cmux, the terminal md launches every Claude session into. Install it with `brew install --cask cmux`, then tell me to open cmux Settings and set `automation.socketControlMode` to `allowAll`. Edit ~/.config/cmux/cmux.json yourself only if I say to go ahead: back it up to a timestamped .bak first, keep it valid JSONC, then run `cmux reload-config` and `cmux config doctor`. The default `cmuxOnly` refuses md and Switchboard without erroring - sessions fall back to a plain terminal tab and nothing says why. An empty `which cmux` is normal: md finds the CLI inside the app bundle, so do not put it on PATH.

Finish by reporting the `md doctor` rows that are still not green, and anything you had to hand back to me.

Never modify anything inside the medallion product checkout.

What it needs from you

Apple Silicon Mac
No Intel build yet. sysctl -n hw.optional.arm64 prints 1.
Homebrew
You install this one. Its installer prompts for your sudo password, so no script can run it for you. On Apple Silicon it has to be at /opt/homebrew.
uv
Any recent one: curl -LsSf https://astral.sh/uv/install.sh | sh. medallion pins a narrower range, and md setup installs that version for you.
medallion checkout
Anywhere you like. md walks up from your cwd, then asks; md config set main_repo <path> pins it. md never clones it for you.
Postgres.app
The other one you install yourself: postgresapp.com, then Initialize, then Preferences → Start at login. Every worktree shares this one server, on :5432 by default. Already running the docker stack? md setup offers to move the native services to :5433/:6380 so both can run at the same time.
cmux
The terminal every Claude session opens in: brew install --cask cmux, then set automation.socketControlMode to allowAll in its Settings. The default refuses md without a word, and sessions land in a plain terminal tab instead. One or two at a time you can live with. Twenty you cannot.
GitHub access
Both repos are internal to trymedallion. SSH to clone, plus an authenticated gh, which md brief, release, babysit, review and desktop install all read through. Waiting on access? The one path that needs none of it is folded under Switchboard.

That is the whole list. direnv, mprocs, watchman, node, yarn, libpq, libmagic, cairo, glib, pango, redis and Python are md setup's job. Docker is not needed on the native path.

Switchboard

The CLI runs the loop from any terminal. The app is what keeps twenty changes in flight navigable: one inbox for every PR you own or owe a review, every worktree with its logs and its Claude sessions, and what happened in each one still there weeks later. Every button is an md command you could type yourself. 

md desktop install

Needs an authenticated gh — the release lives on an internal repo.

Takes seconds, drops the app in /Applications, and clears the quarantine flag macOS would otherwise refuse to open it past. ⌘⇧M toggles the window, and it updates itself from then on.

▶ No GitHub access yet? 
curl -fsSL https://switchboard.medallion.md/install.sh | sh

The same build, by the one path that needs nothing from GitHub. Send this line to someone still waiting on access: the app's Setup space installs md itself from the wheel on the same release.

▶ You can keep docker

Native mode runs two things machine-wide: Postgres.app and a Homebrew redis. Both used to want the exact host ports medallion's compose publishes for its own db and redis containers, so whichever started first won and the other side failed to bind. Trying native meant shutting docker down, and going back meant quitting Postgres.app and stopping redis by hand.

Now the native pair moves instead. Docker keeps :5432 and :6379 exactly as they are, so every compose file, psql and TablePlus connection you already have keeps working: 

md config set postgres_port 5433
md config set redis_port 6380
md setup --fix

Postgres.app owns its own port, so that one is a field you set: open it, pick the server, Server Settings → Port → 5433. md setup offers this whole exchange the moment it notices docker holding the ports, and md doctor tells you when both stacks are clear of each other. Both can then be up at the same time.

md config set postgres_port 5432 puts it back — two commands out, and nothing to rebuild. Nobody has benchmarked what you would be giving up, because the moment you stop waiting for a container to come up you stop caring what the number was.

▶ Or by hand

The same install without an agent, and what you want if you are going to work on md itself.

  1. 1. Clone and install

    git clone git@github.com:trymedallion/medallion-dev-cli.git
cd medallion-dev-cli && uv tool install --editable .

    Editable on purpose: git pull is the whole update story, and the desktop app runs this same tree.

  2. 2. Install the rest

    md setup

    Prompts per action. --dry-run to preview, --yes for none.

  3. 3. Wire up the shell

    command md shell install zsh
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
exec zsh

    After step 2, because step 2 is what installs direnv. command md dodges oh-my-zsh's alias md='mkdir -p'. Skip the hook and worktrees run on stale ports without saying so.

  4. 4. Check it

    md doctor

    Every red row carries its own fix command. Read architecture first on a Mac migrated from Intel: the rows below it are downstream of the same cause.

  5. 5. Install the app

    Either line from Switchboard above. A green md doctor means the CLI is done, not that the install is.

  6. 6. Install cmux

    brew install --cask cmux

    Then open cmux Settings and set automation.socketControlMode to allowAll. The default refuses md without a word, so sessions land in a plain terminal tab instead.