windmill/README_WORKMUX_DEV.md

Windmill Development with workmux

This guide covers the workmux-based development setup for Windmill. Each worktree gets its own tmux window with a Claude Code agent, a backend server (with auto-reload), and a frontend dev server — all on isolated ports.

Prerequisites

• tmux
• Rust toolchain (rustup)
• Node.js + npm
• PostgreSQL running locally (see backend/.env)

Installation

1. Install workmux

cargo install workmux

2. Install the Claude Code plugin

workmux claude install

This lets workmux manage Claude Code agents in worktree panes.

3. Install cargo-watch

Used for auto-recompiling the backend on file changes:

cargo install cargo-watch

4. Install llm CLI (required for auto branch naming)

workmux uses the llm CLI to automatically generate branch names from prompts. Install it with:

uv tool install llm
llm install llm-anthropic

Then set your Anthropic API key:

llm keys set anthropic
# paste your API key when prompted

5. Recommended: shell alias and autocomplete

Set up a wm alias for convenience:

# Add to your ~/.zshrc
alias wm="workmux"

Setting up zsh autocomplete is also recommended — see the workmux docs for instructions.

Port Slot System

Each worktree is assigned a slot that determines its ports:

Slot	Backend	Frontend
0	8000	3000
1	8010	3010
2	8020	3020
3	8030	3030
...	...	...

• Slot 0 is reserved for the main worktree (default cargo run / npm run dev).
• Without WM_SLOT, the script auto-assigns the first available slot (starting from 1) and prints it.
• With WM_SLOT=N, it uses that slot and errors if the ports are taken.

SSH Port Forwarding

If you develop over SSH, add this to ~/.ssh/config on your local machine to pre-configure tunnels for each slot:

Host windmill-dev
  HostName <remote-ip>
  User <username>
  # Slot 0 (main worktree)
  LocalForward 8000 localhost:8000
  LocalForward 3000 localhost:3000
  # Slot 1
  LocalForward 8010 localhost:8010
  LocalForward 3010 localhost:3010
  # Slot 2
  LocalForward 8020 localhost:8020
  LocalForward 3020 localhost:3020
  # Slot 3
  LocalForward 8030 localhost:8030
  LocalForward 3030 localhost:3030

Then connect once and all tunnels are active:

ssh windmill-dev

Access the frontend at http://localhost:<frontend-port> in your local browser.

Quickstart

# Create a new worktree (auto-assigns slot, prints ports)
workmux add my-feature

# Or with an explicit slot
WM_SLOT=2 workmux add my-feature

# Create a worktree and immediately send a prompt to the agent
workmux add -A -p "fix the login bug in auth.rs"

The add command creates the worktree but does not open it. To open the tmux window and start working:

workmux open my-feature

This will open a tmux window with three panes:

• Claude Code agent (focused)
• Backend: cargo watch -x run on the assigned port (auto-reloads on save)
• Frontend: npm run dev proxying to the backend

When using -A with add, the worktree is created and opened automatically, and the prompt is sent to the agent right away.

Check which ports were assigned:

cat <worktree-path>/.env.local

Sending work to the agent

# Send a prompt to the agent in a worktree
workmux send my-feature "fix the login bug in auth.rs"

# Check agent status
workmux status

Merging and cleaning up

We never merge worktrees directly — always create a PR on GitHub and let it be merged there. Once the PR is merged, clean up the worktree:

# Close the tmux window but keep the worktree
workmux close my-feature

# After your PR is merged, remove the worktree, branch, and tmux window
workmux rm my-feature

Note

: Do not use workmux merge. Always go through a PR to get your changes into main. You can ask the Claude Code agent in the worktree to create the PR for you.

Configuration

The setup is defined in .workmux.yaml at the repo root. Key sections:

• post_create: Runs scripts/worktree-env to generate .env.local with port assignments
• panes: Defines the tmux layout (agent, backend, frontend)
• files.copy: Copies backend/.env and scripts/ into each worktree
• files.symlink: Symlinks node_modules and .svelte-kit to avoid reinstalling per worktree

Login

Default credentials: admin@windmill.dev / changeme