webmux Docs | Commands, Configuration, and Runtime Reference

Overview

webmux is a Bun-powered dashboard and CLI for managing parallel AI coding worktrees. It owns the worktree lifecycle, tmux layout, runtime env materialization, service health checks, and linked PR or issue context.

Install

webmux init expects a git repository and checks the local toolchain before it writes configuration. The dashboard itself is started with webmux serve.

Prerequisites

bun

CLI runtime, package manager, and backend runtime.

webmux init enforces Bun >= 1.3.5.

git

Worktree creation, branch management, and repository root discovery.

tmux

Session and pane orchestration behind the dashboard and CLI open/add flows.

python3

Helper runtime used by the event bridge for managed agent hooks.

gh

optional

Optional, but enables GitHub PR, CI, and review-comment context in the UI.

If installed, webmux init also checks gh auth status.

docker

optional

Optional, but required for docker runtime profiles and sandbox mounts.

Quick start

This is the shortest path from a fresh machine to a working browser dashboard on http://localhost:5111.

Step 2

Initialize your repo

Create a project config in the repository you want to manage.

cd /path/to/your/project
webmux init

Checks dependencies, verifies Bun, optionally checks gh auth status, then creates or adapts .webmux.yaml at the git root.

Step 4

Create your first worktree

Use the dashboard to spin up an agent, terminal panes, and ports.

Open http://localhost:5111

Each managed worktree gets metadata, runtime env materialization, and a tmux layout based on the selected profile.

CLI reference

The root command surface includes dashboard serving, setup, service management, shell completion, and lifecycle-aware worktree subcommands.

Root commands

serve

webmux serve [--port <number>] [--debug]

Start the dashboard server for the current project.

Requires .webmux.yaml at the git root.
Reads .env.local first, then .env, before launching.
Uses PORT as a fallback when --port is omitted.

init

webmux init

Interactive project setup for .webmux.yaml.

Must run inside a git repository.
Checks dependencies and Bun version, then offers Claude, Codex, or manual starter generation.
If gh is installed, warns when gh auth login is still needed.

service

webmux service <install|uninstall|status|logs> [--port <number>]

Manage webmux as a user-level service on Linux or macOS.

Uses systemctl --user on Linux and launchctl on macOS.
Writes a service file pointed at webmux serve --port ...
Not supported on other platforms.

update

webmux update

Upgrade the globally installed CLI with Bun.

Runs bun install --global webmux@latest under the hood.

completion

webmux completion <bash|zsh>

Emit shell completion setup for bash or zsh.

Completions include worktree branch names for open, close, remove, and merge.
Add the output to your shell config with eval "$(webmux completion zsh)" or the bash equivalent.

Worktree commands

add

webmux add [branch] [--profile <name>] [--agent <claude|codex>] [--prompt <text>] [--env KEY=VALUE]

Create a managed worktree through the same lifecycle the dashboard uses.

Branch is optional when your setup can infer or auto-name it from the prompt.
Repeat --env KEY=VALUE to override runtime env values for that worktree.
After creation, webmux switches tmux to the new worktree window.

list

webmux list

List managed worktrees, open or closed state, and saved profile / agent metadata.

open

webmux open <branch>

Open an existing worktree session and rebuild its tmux layout.

close

webmux close <branch>

Close the tmux session for a worktree without deleting the worktree directory.

remove

webmux remove <branch>

Delete a managed worktree and run preRemove if configured.

merge

webmux merge <branch>

Merge the worktree branch into workspace.mainBranch and remove the worktree.

Configuration

.webmux.yaml is loaded from the git root and normalized into the final project config shape. The example below includes services, profiles, docker mounts, startup envs, integrations, lifecycle hooks, and auto naming.

Full example

name: My Project

workspace:
  mainBranch: main
  worktreeRoot: ../worktrees
  defaultAgent: claude

services:
  - name: API
    portEnv: PORT
    portStart: 3000
    portStep: 10
    urlTemplate: http://127.0.0.1:${PORT}
  - name: FE
    portEnv: FRONTEND_PORT
    portStart: 5173
    portStep: 10
    urlTemplate: http://127.0.0.1:${FRONTEND_PORT}

profiles:
  default:
    runtime: host
    envPassthrough:
      - GITHUB_TOKEN
    panes:
      - id: agent
        kind: agent
        focus: true
      - id: shell
        kind: shell
        split: right
        sizePct: 25
      - id: frontend
        kind: command
        split: bottom
        cwd: repo
        command: FRONTEND_PORT=$FRONTEND_PORT bun run dev

  sandbox:
    runtime: docker
    image: webmux-sandbox
    envPassthrough:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
    mounts:
      - hostPath: ~/.codex
        guestPath: /root/.codex
        writable: true
    panes:
      - id: agent
        kind: agent
        focus: true

startupEnvs:
  NODE_ENV: development
  FEATURE_FLAG: true

integrations:
  github:
    linkedRepos:
      - repo: myorg/related-service
        alias: related
        dir: ../related-service
  linear:
    enabled: true

lifecycleHooks:
  postCreate: scripts/post-create.sh
  preRemove: scripts/pre-remove.sh

auto_name:
  provider: claude
  model: claude-3-5-haiku-latest
  system_prompt: >
    Generate a concise git branch name from the task description.
    Return only the branch name.

Schema reference

These tables reflect the current config parser and defaults in the codebase rather than a hand-maintained marketing summary.

Project and workspace

Top-level project identity and default workspace behavior. These values are loaded from the git root containing .webmux.yaml.

Key	Type	Required	Default	Description
name	string	no	Webmux	Project name shown in the sidebar and browser title.
workspace.mainBranch	string	no	main	Base branch used for merge targets and new worktrees.
workspace.worktreeRoot	string	no	../worktrees	Relative or absolute directory where managed worktrees are created.
workspace.defaultAgent	claude \| codex	no	claude	Default agent kind used when a worktree does not specify one explicitly.

Services

Service definitions drive port allocation, health checks, and optional direct links in the UI.

Key	Type	Required	Default	Description
services[].name	string	yes	-	Display name shown in the dashboard.
services[].portEnv	string	yes	-	Runtime env key where the allocated port is injected.
services[].portStart	number	no	-	Base port for auto-allocation across worktrees.
services[].portStep	number	no	1	Increment between worktree slots when ports are auto-allocated.
services[].urlTemplate	string	no	-	Expanded with runtime env values to generate a clickable service URL.

Profiles

Profiles describe how a worktree runs: runtime, env passthrough, pane layout, prompts, and optional docker settings.

Key	Type	Required	Default	Description
profiles.<name>.runtime	host \| docker	yes	-	Execution runtime for the profile.
profiles.<name>.envPassthrough	string[]	no	[]	Host env vars forwarded into the agent or container runtime.
profiles.<name>.systemPrompt	string	no	-	Prompt template applied to the agent for that profile.
profiles.<name>.yolo	boolean	no	-	Enables permissive execution flags for compatible agent CLIs.
profiles.<name>.image	string	conditional	-	Docker image name. Required when runtime is docker.
profiles.<name>.mounts[]	MountSpec[]	no	-	Host/container mounts for docker profiles.
profiles.<name>.panes[]	PaneTemplate[]	yes	-	Ordered tmux pane layout for the worktree session.

Pane templates and mounts

Pane entries control what opens in tmux, while mount specs shape docker filesystem access.

Key	Type	Required	Default	Description
panes[].id	string	no	pane-N	Stable pane identifier used by the session layout.
panes[].kind	agent \| shell \| command	yes	-	Pane behavior. command requires a startup command string.
panes[].split	right \| bottom	no	-	Split direction relative to the previously created pane.
panes[].sizePct	number	no	-	Optional pane size percentage for the split.
panes[].focus	boolean	no	-	Marks the pane that should receive initial focus.
panes[].command	string	conditional	-	Startup command for command panes.
panes[].cwd	repo \| worktree	no	-	Whether the pane starts in the repository root or the worktree root.
mounts[].hostPath	string	yes	-	Host path to mount into docker.
mounts[].guestPath	string	no	-	Container mount path. When omitted, the host path is reused.
mounts[].writable	boolean	no	false	When true, the mount is read-write instead of read-only.

Startup envs and integrations

These sections enrich the runtime environment and hook webmux into related tools and repositories.

Key	Type	Required	Default	Description
startupEnvs.<KEY>	string \| boolean	no	{}	Additional env vars materialized into the managed worktree runtime.
integrations.github.linkedRepos[].repo	string	yes	-	GitHub repo slug used for linked PR and CI context.
integrations.github.linkedRepos[].alias	string	no	-	Short label shown in the UI. Defaults to the repo basename.
integrations.github.linkedRepos[].dir	string	no	-	Optional repo path used for editor or deep-link integrations.
integrations.linear.enabled	boolean	no	true	Turns Linear issue fetching on or off globally.

Lifecycle hooks and auto naming

Automation sections that run scripts or generate branch names for new worktrees.

Key	Type	Required	Default	Description
lifecycleHooks.postCreate	string	no	-	Shell command run after a managed worktree is created but before panes start.
lifecycleHooks.preRemove	string	no	-	Shell command run before a managed worktree is removed.
auto_name.provider	claude \| codex	yes	-	CLI backend used for branch-name generation.
auto_name.model	string	no	-	Optional model name passed through to the selected CLI.
auto_name.system_prompt	string	no	-	Overrides the built-in branch naming prompt.

Automation and runtime details

The details below are the implementation-level behaviors that matter when you automate webmux, write lifecycle hooks, or rely on generated branch names and port allocation.

Runtime environment reference

webmux writes runtime env files for managed worktrees and injects these variables into panes and lifecycle hooks.

Key	Type	Required	Default	Description
WEBMUX_WORKTREE_ID	string	set by webmux	-	Stable worktree identifier used by the control plane and runtime metadata.
WEBMUX_BRANCH	string	set by webmux	-	Resolved branch or worktree name for the managed worktree.
WEBMUX_PROFILE	string	set by webmux	-	Selected profile name for that worktree.
WEBMUX_AGENT	string	set by webmux	-	Resolved agent kind, such as claude or codex.
WEBMUX_RUNTIME	string	set by webmux	-	Resolved runtime kind, such as host or docker.
WEBMUX_WORKTREE_PATH	string	set by webmux	-	Absolute filesystem path to the managed worktree.
WEBMUX_CONTROL_URL	string	managed panes	-	Internal control endpoint used by the agent runtime event bridge.
WEBMUX_CONTROL_TOKEN	string	managed panes	-	Bearer token for authenticated control-plane event posts.

Keyboard shortcuts

The browser dashboard keeps the common worktree actions on a small, memorable set of keyboard shortcuts.

Everything you need to install, configure, and operate webmux.