You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Web dashboard for [workmux](https://github.com/raine/workmux). Provides a browser UI with embedded terminals, PR status monitoring, and CI integration on top of workmux's worktree + tmux orchestration.
3
+
A web dashboard for managing parallel AI coding agents. Built on top of [workmux](https://github.com/raine/workmux), which handles git worktrees and tmux orchestration — wmdev adds a browser UI with embedded terminals, live status tracking, and CI integration.
[workmux](https://github.com/raine/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.
9
+
### Embedded Terminals
10
10
11
-
workmux is configured via `.workmux.yaml` in the project root. See the [workmux README](https://github.com/raine/workmux) for full documentation.
11
+
<!-- gif -->
12
12
13
-
## What wmdev adds
13
+
View and interact with your agents directly in the browser. Each worktree gets its own terminal session, streamed live via WebSocket. You can watch agents work, send prompts, and switch between worktrees instantly — no need to juggle tmux windows manually.
14
14
15
-
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:
See pull request status, CI check results, and failed log output right next to each worktree. No more switching to GitHub to check if your agent's PR passed CI.
20
+
21
+
### Create & Manage Worktrees
22
+
23
+
<!-- gif -->
24
+
25
+
Spin up new worktrees with one click. Pick a profile, type a prompt, and wmdev creates the worktree, starts the agent, and begins streaming output. Merge or remove worktrees when you're done.
26
+
27
+
### Service Health Monitoring
28
+
29
+
<!-- gif -->
30
+
31
+
Track dev server ports across worktrees. wmdev polls configured services and shows live health badges so you know which worktrees have their servers running.
32
+
33
+
### Docker Sandbox Mode
34
+
35
+
<!-- gif -->
36
+
37
+
Run agents in isolated Docker containers for untrusted or experimental work. wmdev manages the container lifecycle, port forwarding, and volume mounts automatically.
38
+
39
+
## Quick Start
33
40
34
41
```bash
35
42
# 1. Install prerequisites
@@ -42,78 +49,21 @@ bun install -g wmdev
42
49
43
50
# 3. Set up your project
44
51
cd /path/to/your/project
45
-
workmux init # creates .workmux.yaml with sensible defaults
46
-
47
-
# 4. (Optional) Create a .wmdev.yaml for dashboard-specific config
48
-
# See Configuration below
52
+
wmdev init # creates .workmux.yaml and .wmdev.yaml
49
53
50
-
# 5. Start the dashboard
51
-
wmdev # UI on http://localhost:5111
52
-
wmdev --port 8080 # custom port
54
+
# 4. Start the dashboard
55
+
wmdev # opens on http://localhost:5111
53
56
```
54
57
55
58
## Configuration
56
59
57
60
wmdev uses two config files in the project root:
58
61
59
-
-**`.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](https://github.com/raine/workmux).
60
-
-**`.wmdev.yaml`** — dashboard-specific config. Controls service health checks, worktree profiles, linked repos for PR monitoring, and Docker sandbox settings.
61
-
62
-
### `.wmdev.yaml` schema
63
-
64
-
```yaml
65
-
# Project name displayed in the sidebar header and browser tab title.
66
-
# Falls back to "Dashboard" if omitted.
67
-
name: string
68
-
69
-
# Services to monitor — each maps a display name to a port env var.
70
-
# The dashboard polls these ports and shows health status badges.
71
-
# When portStart is set, wmdev auto-allocates ports for new worktrees
72
-
# and writes them to .env.local (no post_create hook needed).
73
-
services:
74
-
- name: string # Display name (e.g. "BE", "FE")
75
-
portEnv: string # Env var holding the port (e.g. "BACKEND_PORT")
76
-
portStart: number # (optional) Base port for slot 0 (e.g. 5111)
77
-
portStep: number # (optional) Increment per worktree slot (default: 1)
78
-
79
-
# Profiles define the environment when creating a worktree via the dashboard.
80
-
profiles:
81
-
default: # Required — used when no profile is specified
82
-
name: string # Profile identifier
83
-
systemPrompt: string # (optional) Instructions for the AI agent.
84
-
# Supports ${VAR} placeholders expanded from .env.local.
85
-
envPassthrough: string[] # (optional) Env vars to pass to the agent process
| `linkedRepos[].alias` | string | no | Short label for the UI (defaults to repo name) |
127
+
| `linkedRepos[].alias` | string | no | Short label for the UI |
175
128
176
-
### Auto-generated branch names
129
+
</details>
177
130
178
-
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.
**Backend** — Bun/TypeScript HTTP + WebSocket server (`backend/src/server.ts`):
187
-
188
-
- **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.
189
-
- **WebSocket** (`/ws/*`) — Bidirectional terminal bridge between xterm.js in the browser and tmux sessions on the server.
190
-
191
-
**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.
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.
200
-
201
-
Output is buffered (up to 1 MB) so reconnecting clients receive recent history immediately.
202
-
203
-
### Worktree profiles
204
-
205
-
| Profile | What it does |
206
-
|---------|-------------|
207
-
| `default` | Delegates to workmux — uses the pane layout and commands from `.workmux.yaml`. wmdev doesn't manage panes or processes; workmux handles it all. |
208
-
| `sandbox` | Managed by wmdev. Launches a Docker container, sets up agent + shell panes, and publishes service ports via `docker run -p`. |
209
-
210
-
### Docker sandbox containers
211
-
212
-
For sandbox profiles, wmdev manages Docker containers directly:
213
-
214
-
1. **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.
215
-
2. **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.
216
-
3. **Environment** — All `.env.local` vars + `envPassthrough` vars + `HOME`, `TERM`, `IS_SANDBOX=1`.
217
-
4. **Cleanup** — Containers are removed when the worktree is removed or merged.
218
-
219
-
## Prerequisites
220
-
221
-
| Tool | Min version | Purpose |
222
-
|------|-------------|---------|
223
-
| [**bun**](https://bun.sh) | 1.3.5+ | Runtime for backend and frontend |
0 commit comments