wmdev

wmdev

Web dashboard for workmux. Provides a browser UI with embedded terminals, PR status monitoring, and CI integration on top of workmux's worktree + tmux orchestration.

https://github.com/user-attachments/assets/fa13366d-e758-4221-94bf-13a5738bf7e7

What is workmux?

workmux is a CLI tool that orchestrates git worktrees and tmux. It pairs each worktree with a tmux window, provisions files (copy/symlink), runs lifecycle hooks, and has first-class AI agent support. A single workmux add creates the worktree, opens a tmux window with configured panes, and starts your agent. workmux merge merges the branch, deletes the worktree, closes the window, and cleans up branches.

workmux is configured via .workmux.yaml in the project root. See the workmux README for full documentation.

What wmdev adds

wmdev is a web UI that wraps workmux. It delegates core worktree lifecycle operations to the workmux CLI and adds browser-based features on top:

Responsibility	Handled by
Create/remove/merge worktrees	workmux (wmdev calls workmux add, workmux rm, workmux merge)
Pane layout and agent launch (default profile)	workmux (uses .workmux.yaml pane config)
Open/focus a worktree's tmux window	workmux (workmux open)
List worktrees and agent status	workmux (workmux list, workmux status)
File provisioning and lifecycle hooks	workmux (.workmux.yaml files and post_create)
Port allocation for worktree services	wmdev (when portStart is set in .wmdev.yaml) or workmux (via post_create hook)
Browser terminal (xterm.js ↔ tmux)	wmdev
Service health monitoring (port polling)	wmdev
PR status tracking and badges	wmdev (polls gh pr list)
CI check status and failed log viewing	wmdev (calls gh run view)
Send prompts / PR comments to agents	wmdev (via tmux load-buffer)
Docker sandbox container lifecycle	wmdev (manages docker run/rm directly)

Quick start

# 1. Install prerequisites
cargo install workmux          # or: brew install raine/workmux/workmux
sudo apt install tmux           # or: brew install tmux
curl -fsSL https://bun.sh/install | bash

# 2. Install wmdev
bun install -g wmdev

# 3. Set up your project
cd /path/to/your/project
workmux init                   # creates .workmux.yaml with sensible defaults

# 4. (Optional) Create a .wmdev.yaml for dashboard-specific config
#    See Configuration below

# 5. Start the dashboard
wmdev                          # UI on http://localhost:5111
wmdev --port 8080              # custom port

Configuration

wmdev uses two config files in the project root:

• .workmux.yaml — workmux's own config. Controls worktree directory, pane layout, agent selection, file provisioning, lifecycle hooks, merge strategy, and more. See the workmux docs.
• .wmdev.yaml — dashboard-specific config. Controls service health checks, worktree profiles, linked repos for PR monitoring, and Docker sandbox settings.

.wmdev.yaml schema

# Project name displayed in the sidebar header and browser tab title.
# Falls back to "Dashboard" if omitted.
name: string

# Services to monitor — each maps a display name to a port env var.
# The dashboard polls these ports and shows health status badges.
# When portStart is set, wmdev auto-allocates ports for new worktrees
# and writes them to .env.local (no post_create hook needed).
services:
  - name: string             # Display name (e.g. "BE", "FE")
    portEnv: string          # Env var holding the port (e.g. "BACKEND_PORT")
    portStart: number        # (optional) Base port for slot 0 (e.g. 5111)
    portStep: number         # (optional) Increment per worktree slot (default: 1)

# Profiles define the environment when creating a worktree via the dashboard.
profiles:
  default:                   # Required — used when no profile is specified
    name: string             # Profile identifier
    systemPrompt: string     # (optional) Instructions for the AI agent.
                             # Supports ${VAR} placeholders expanded from .env.local.
    envPassthrough: string[] # (optional) Env vars to pass to the agent process

  sandbox:                   # (optional) Docker-based sandboxed profile
    name: string             # Profile identifier
    image: string            # Docker image name (must be pre-built)
    systemPrompt: string     # (optional) Agent instructions (supports ${VAR})
    envPassthrough: string[] # (optional) Host env vars forwarded into the container
    extraMounts:             # (optional) Additional bind mounts
      - hostPath: string     # Host path (supports ~ for $HOME)
        guestPath: string    # (optional) Mount point inside container (defaults to hostPath)
        writable: boolean    # (optional) true = read-write, false/omit = read-only

# Monitor PRs from other GitHub repos and show their status alongside
# worktree branches that share the same branch name.
linkedRepos:
  - repo: string             # GitHub repo slug (e.g. "org/repo")
    alias: string            # (optional) Short label shown in the UI

Defaults

If .wmdev.yaml is missing or empty:

services: []
profiles:
  default:
    name: default
linkedRepos: []

Example

name: My Project

services:
  - name: BE
    portEnv: BACKEND_PORT
    portStart: 5111
    portStep: 10
  - name: FE
    portEnv: FRONTEND_PORT
    portStart: 5112
    portStep: 10

profiles:
  default:
    name: default

  sandbox:
    name: sandbox
    image: my-sandbox
    envPassthrough:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
    extraMounts:
      - hostPath: ~/.codex
        guestPath: /root/.codex
        writable: true
    systemPrompt: >
      You are running inside a sandboxed container.
      Backend port: ${BACKEND_PORT}. Frontend port: ${FRONTEND_PORT}.

linkedRepos:
  - repo: myorg/related-service
    alias: svc

Parameter reference

Parameter	Type	Required	Description
name	string	no	Project name shown in the sidebar header and browser tab title. Defaults to "Dashboard"
services[].name	string	yes	Display name shown in the dashboard
services[].portEnv	string	yes	Env var containing the service port (read from each worktree's .env.local)
services[].portStart	number	no	Base port for slot 0. When set, wmdev auto-allocates ports for new worktrees
services[].portStep	number	no	Port increment per worktree slot (default: 1). Slot 0 is reserved for main
profiles.default.name	string	yes	Identifier for the default profile
profiles.default.systemPrompt	string	no	System prompt for the agent; ${VAR} placeholders expanded at runtime
profiles.default.envPassthrough	string[]	no	Env vars passed through to the agent process
profiles.sandbox.name	string	yes (if used)	Identifier for the sandbox profile
profiles.sandbox.image	string	yes (if used)	Docker image for containers
profiles.sandbox.systemPrompt	string	no	System prompt for sandbox agents; ${VAR} placeholders expanded at runtime
profiles.sandbox.envPassthrough	string[]	no	Host env vars forwarded into the Docker container
profiles.sandbox.extraMounts[].hostPath	string	yes	Host path to mount (~ expands to $HOME)
profiles.sandbox.extraMounts[].guestPath	string	no	Container mount path (defaults to hostPath)
profiles.sandbox.extraMounts[].writable	boolean	no	true for read-write; omit or false for read-only
linkedRepos[].repo	string	yes	GitHub repo slug (e.g. org/repo)
linkedRepos[].alias	string	no	Short label for the UI (defaults to repo name)

Auto-generated branch names

If your .workmux.yaml has auto_name.model configured, the create-worktree dialog will automatically generate a branch name from the prompt using that LLM. This is a workmux feature — wmdev detects it and enables the UI flow accordingly.

Architecture

Backend — Bun/TypeScript HTTP + WebSocket server (backend/src/server.ts):

• REST API (/api/*) — CRUD for worktrees. Wraps the workmux CLI to create/remove/merge worktrees. Enriches each worktree with directory, assigned ports, service health, PR status, and agent state.
• WebSocket (/ws/*) — Bidirectional terminal bridge between xterm.js in the browser and tmux sessions on the server.

Frontend — Svelte 5 SPA with Tailwind CSS and xterm.js (frontend/src/). Two-panel layout: worktree sidebar + embedded terminal. Polls the REST API for status updates. Responsive with mobile pane navigation.

Terminal streaming

When a worktree is selected, the frontend opens a WebSocket to /ws/<worktree>. The backend spawns a PTY via script and attaches to a grouped tmux session — a separate view into the same windows. This allows the dashboard and a real terminal to view the same worktree simultaneously.

Output is buffered (up to 1 MB) so reconnecting clients receive recent history immediately.

Worktree profiles

Profile	What it does
default	Delegates to workmux — uses the pane layout and commands from .workmux.yaml. wmdev doesn't manage panes or processes; workmux handles it all.
sandbox	Managed by wmdev. Launches a Docker container, sets up agent + shell panes, and publishes service ports via docker run -p.

Docker sandbox containers

For sandbox profiles, wmdev manages Docker containers directly:

• Launch — docker run -d -p <ports> with the configured image, mounts, and env vars. Runs as the host user (--user uid:gid) so file ownership matches.
• Mounts — Worktree dir (rw), main repo .git (rw), main repo root (ro), ~/.claude (dir) and ~/.claude.json (settings file), plus any extraMounts. Conditionally mounts ~/.gitconfig, ~/.ssh, ~/.config/gh if they exist.
• Environment — All .env.local vars + envPassthrough vars + HOME, TERM, IS_SANDBOX=1.
• Cleanup — Containers are removed when the worktree is removed or merged.

Prerequisites

Tool	Min version	Purpose
bun	1.3.5+	Runtime for backend and frontend
workmux	latest	Worktree + tmux orchestration
tmux	3.x	Terminal multiplexer
git	2.x	Worktree management
gh	2.x	PR and CI status (optional — needed for PR badges and CI logs)
docker	28+	Only needed for sandbox profile

Environment variables

Variable	Default	Description
BACKEND_PORT	5111	Backend API port (also configurable via --port)

Keyboard shortcuts

Shortcut	Action
Cmd+Up/Down	Navigate between worktrees
Cmd+K	Create new worktree
Cmd+M	Merge selected worktree
Cmd+D	Remove selected worktree

API

Method	Endpoint	Description
GET	/api/config	Load dashboard config
GET	/api/worktrees	List all worktrees with status, ports, service health, and PR data
POST	/api/worktrees	Create a worktree ({ branch?, profile?, agent?, prompt? })
DELETE	/api/worktrees/:name	Remove a worktree
POST	/api/worktrees/:name/open	Open/focus a worktree's tmux window
POST	/api/worktrees/:name/merge	Merge worktree into main + cleanup
GET	/api/worktrees/:name/status	Get agent status for a worktree
POST	/api/worktrees/:name/send	Send a prompt to the agent's tmux pane
GET	/api/ci-logs/:runId	Fetch failed CI run logs
WS	/ws/:worktree	Terminal WebSocket (xterm.js ↔ tmux)

Development

./dev.sh          # backend + frontend with hot reload, UI on :5112

Or start them separately:

# Terminal 1: backend (auto-reloads on save)
cd backend && bun run dev

# Terminal 2: frontend (Vite dev server)
cd frontend && bun run dev

The frontend dev server runs on port 5112 and proxies /api/* and /ws/* to the backend on 5111.