windmill-labs/webmux

windmill-labs profile

Latest recorded source activity: March 9, 2026 at 13:55

SkillsMP catalog refreshed: October 17, 2026 at 00:09

skills collected: 1

GitHub stars: 56
GitHub forks: 7

Repository README

Repository README source: README.md

Read the source README

Expand full README

# webmux A web dashboard for managing parallel AI coding agents. webmux owns git worktree lifecycle, tmux layout, agent runtime events, service health monitoring, and sandbox containers directly, and now also ships a separate mobile-friendly chat UI for checking in on worktrees away from your desktop. ![webmux demo](https://github.com/windmill-labs/webmux/raw/main/site/static/videos/demo.gif) ## Features ### Create & Manage Worktrees ![create worktree](https://github.com/windmill-labs/webmux/raw/main/site/static/videos/create.gif) Spin up new worktrees with one click. Pick a profile, type a prompt, and webmux creates the worktree, starts the agent, and begins streaming output. Changed your mind about the profile? Switch it later from the worktree menu (or `webmux profile <branch> <profile>`) — the session restarts with the new pane layout and commands, resuming the agent conversation. Merge or remove worktrees when you're done. ### Embedded Terminals 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. ### Mobile-Friendly Agents Chat webmux also serves a second, simplified agents UI on a separate port. It is primarily meant to give you a much better mobile UX: a worktree list, a simple chat screen, and quick access to service and PR badges without trying to squeeze a full terminal dashboard onto a phone. ### PR, CI & Comments ![PR and CI](https://github.com/windmill-labs/webmux/raw/main/site/static/videos/ci.gif) See pull request status, CI check results, and review comments right next to each worktree. No more switching to GitHub to check if your agent's PR passed CI. ### Service Health Monitoring ![service health](https://github.com/windmill-labs/webmux/raw/main/site/static/videos/health.gif) Track dev server ports across worktrees. webmux polls configured services and shows live health badges so you know which worktrees have their servers running. ### Docker Sandbox Mode Run agents in isolated Docker containers for untrusted or experimental work. webmux manages the container lifecycle, port forwarding, and volume mounts automatically. ### Linear Integration ![linear integration](https://github.com/windmill-labs/webmux/raw/main/site/static/videos/linear.gif) See your assigned Linear issues alongside your worktrees. Webmux matches branches to issues automatically, so you can browse your backlog, pick an issue, and spin up a worktree for it in one click. **Auto-create from labels.** When the server polls your assigned Linear issues, it acts on two labels: - **`webmux`** — auto-creates a worktree for the issue, seeded with the issue title + description as the agent prompt. - **`webmux_oneshot`** — launches the issue via `webmux oneshot` (autonomous run; auto-closes the session and posts the conversation back to the Linear issue when the agent terminates or opens a PR). When both labels are present, `webmux_oneshot` wins. Each issue is processed once while it stays in Todo + labeled. Remove the label and re-add it to retrigger. When the auto-create watcher picks up a `webmux_oneshot` issue, it posts a structured comment on the Linear issue (prefix `` **Webmux pickup — branch `<branch>`** ``) so external automation can track when the autonomous run starts. (Regular `webmux` pickups are user-driven and skip the comment.) **Setup — `LINEAR_API_KEY`.** Everything above needs a [Linear API key](https://linear.app/settings/account/security) in the server's environment. webmux runs as a single machine-wide service started from your home directory, so put the key in `~/.config/webmux/.env` — a `KEY=value` file the server loads at startup regardless of which directory it runs from, so it survives `webmux update`: ```bash mkdir -p ~/.config/webmux echo 'LINEAR_API_KEY=lin_api_...' >> ~/.config/webmux/.env chmod 600 ~/.config/webmux/.env webmux service restart ``` Your assigned issues appear in the dashboard once the service restarts. ## Quick Start ```bash # 1. Install prerequisites sudo apt install tmux # or: brew install tmux sudo apt install python3 # or: brew install python curl -fsSL https://bun.sh/install | bash # 2. Install webmux bun install -g webmux # 3. Set up your project cd /path/to/your/project webmux init # creates .webmux.yaml (the only per-project step) # 4. Start the dashboard webmux serve # dashboard on http://localhost:5111 ``` The primary dashboard remains the best desktop experience. On mobile, the same dashboard swaps the embedded terminal for a chat view on open Codex and Claude worktrees. ### One dashboard, many projects You don't run a separate webmux per project. A single `webmux serve` serves **every project you've added, on one dashboard and one port** — each scoped under its own `/<prefix>` URL. The only per-project requirement is a `.webmux.yaml` in the repo (created by `webmux init`); webmux auto-loads it. - The repo you launch `webmux serve` in is served automatically — but only for that session. It isn't written to `~/.webmux/projects.json`, so it isn't remembered across restarts unless you `webmux project add` it. - Switch projects, or add/remove them, from the project switcher in the dashboard. - Or manage them from the CLI: ```bash webmux project ls # list projects the dashboard is serving webmux project add ~/code/other # add another project (persists; must have a .webmux.yaml) webmux project rm other # remove by prefix webmux project migrate # fold other running webmux servers into this one ``` Projects added with `webmux project add` are remembered in `~/.webmux/projects.json` and reloaded on the next start. Run webmux as a single service per machine with `webmux service install`. If you're upgrading from an older setup that ran one service per project, `webmux project migrate` consolidates those leftover servers into this one (the dashboard shows a banner when it detects them). ## Prerequisites | Tool | Purpose | |------|---------| | [**bun**](https://bun.sh) | Runtime | | **python3** | Per-worktree hook/event helper runtime | | **tmux** | Terminal multiplexer | | **git** | Worktree management | | **gh** | PR and CI status (optional) | | **docker** | Sandbox profile only (optional) | ## Configuration webmux uses a project config file in the project root, plus an optional local overlay: - **`.webmux.yaml`** — Worktree root, pane layout, service ports, profiles, linked repos, and Docker sandbox settings. - **`.webmux.local.yaml`** — Optional local-only overlay for additional `profiles` and `lifecycleHooks`. Profiles are additive, conflicting profile names are replaced by the local definition, and local lifecycle hook commands run after the project-level command for the same hook. <details> <summary><strong>.webmux.yaml example</strong></summary> ```yaml name: My Project workspace: mainBranch: main worktreeRoot: __worktrees defaultAgent: claude autoPull: enabled: true intervalSeconds: 300 services: - name: BE portEnv: PORT portStart: 5111 portStep: 10 - name: FE portEnv: FRONTEND_PORT portStart: 5112 portStep: 10 profiles: default: runtime: host yolo: false envPassthrough: [] panes: - id: agent kind: agent focus: true - id: frontend kind: command split: right workingDir: frontend command: FRONTEND_PORT=$FRONTEND_PORT npm run dev sandbox: runtime: docker yolo: true image: my-sandbox envPassthrough: - AWS_ACCESS_KEY_ID - AWS_SECRET_ACCESS_KEY mounts: - hostPath: ~/.codex guestPath: /root/.codex writable: true systemPrompt: > You are running inside a sandboxed container. Backend port: ${PORT}. Frontend port: ${FRONTEND_PORT}. Custom sandbox images should make `claude` or `codex` available on the container's normal `PATH` (for example with `ENV PATH=/your/tool/bin:$PATH`). webmux does not rely on login-shell dotfiles like `.bashrc` to discover agent binaries inside the container. integrations: github: autoRemoveOnMerge: true linkedRepos: - repo: myorg/related-service alias: svc startupEnvs: NODE_ENV: development auto_name: model: claude-3-5-haiku-latest system_prompt: > Generate a concise git branch name from the task description. Return only the branch name in lowercase kebab-case. lifecycleHooks: postCreate: scripts/post-create.sh preRemove: scripts/pre-remove.sh ``` </details> <details> <summary><strong>.webmux.yaml full schema</strong></summary> | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | no | Project name shown in sidebar and browser tab | | `workspace.mainBranch` | string | no | Base branch used for new worktrees | | `workspace.worktreeRoot` | string | no | Relative or absolute directory for managed worktrees | | `workspace.defaultAgent` | string | no | Default agent for new worktrees | | `workspace.autoPull.enabled` | boolean | no | Periodically fetch and fast-forward merge the main branch (default: `false`) | | `workspace.autoPull.intervalSeconds` | number | no | Seconds between auto-pull attempts (default: `300`, minimum: `30`) | | `services[].name` | string | yes | Display name shown in the dashboard | | `services[].portEnv` | string | yes | Env var containing the service port | | `services[].portStart` | number | no | Base port for auto-allocation | | `services[].portStep` | number | no | Port increment per worktree slot (default: `1`) | | `profiles.<name>.runtime` | string | yes | `host` or `docker` | | `profiles.<name>.yolo` | boolean | no | Enables `--dangerously-skip-permissions` for Claude or `--yolo` for Codex | | `profiles.<name>.panes[]` | array | yes | Pane layout for that profile | | `profiles.<name>.panes[].kind` | string | yes | `agent`, `shell`, or `command` | | `profiles.<name>.panes[].command` | string | yes (for `command`) | Startup command run inside the pane | | `profiles.<name>.panes[].workingDir` | string | no | Directory to `cd` into before running a command pane startup command | | `profiles.default.systemPrompt` | string | no | Agent system prompt; `${VAR}` placeholders expanded at runtime | | `profiles.default.envPassthrough` | string[] | no | Env vars passed to the agent process | | `profiles.sandbox.image` | string | yes (if used) | Docker image for containers | | `profiles.sandbox.systemPrompt` | string | no | Agent system prompt for sandbox | | `profiles.sandbox.envPassthrough` | string[] | no | Host env vars forwarded into the container | | `profiles.sandbox.mounts[].hostPath` | string | yes | Host path to mount (`~` expands to `$HOME`) | | `profiles.sandbox.mounts[].guestPath` | string | no | Container mount path (defaults to `hostPath`) | | `profiles.sandbox.mounts[].writable` | boolean | no | `true` for read-write; omit or `false` for read-only | | `integrations.github.autoRemoveOnMerge` | boolean | no | Automatically remove worktrees when their PR is merged (default: `false`) | | `integrations.github.linkedRepos[].repo` | string | yes | GitHub repo slug (e.g. `org/repo`) | | `integrations.github.linkedRepos[].alias` | string | no | Short label for the UI | | `startupEnvs.<KEY>` | string or boolean | no | Extra env vars materialized into worktree runtime env | | `auto_name.model` | string | no | Model used to generate the branch name when the branch field is left empty; supports Anthropic (`claude-*`), Gemini (`gemini-*`), and OpenAI (`gpt-*`, `chatgpt-*`, `o*`) models | | `auto_name.system_prompt` | string | no | System prompt sent to the auto-name model | | `lifecycleHooks.postCreate` | string | no | Shell command run after a managed worktree is created and its runtime env is materialized, but before the tmux session/panes are started | | `lifecycleHooks.preRemove` | string | no | Shell command run before a managed worktree is removed | </details> Lifecycle hooks run with the worktree as `cwd` and receive the same computed runtime env that the managed panes will use, including `startupEnvs`, allocated service ports, and `WEBMUX_*` metadata. When `auto_name` is enabled, `webmux` calls the provider API directly with structured output and uses `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, or `OPENAI_API_KEY` based on the configured model. ## 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 |

Loading the repository README…

Skills in this repository

Software Developers

1 occupation categories · 100% classified

skill

occupation

description

updated

pr

Software Developers

Open a draft pull request on GitHub. MUST use when you want to create/open a PR.

2026-03-09

Showing 1 of 1 collected skills.

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/windmill-labs/webmux.