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.

Features

Create & Manage Worktrees

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. 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

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

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

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.

Quick Start

# 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

# 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.

Prerequisites

| Tool | Purpose | |------|---------| | bun | 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.

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

| 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 |

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 |