Developer documentation

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

This page turns the current CLI and config surface into a complete docs reference: installation, command usage, schema details, defaults, automation hooks, integrations, and runtime behavior.

View GitHub repo Jump to quick start

Dashboard command

webmux serve

Default port

5111 via --port or PORT

Agents UI port

5112 by default via --agents-port

Main branch default

main

Worktree root default

../worktrees

Default agent

claude

Auto-pull default

disabled

Linear integration default

enabled: true

Overview Install Quick start CLI reference Configuration Schema reference Automation Shortcuts

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, linked PR or issue context, and a separate agents chat UI that is primarily meant to provide a better mobile UX.

Install

webmux init expects a git repository and checks the local toolchain before it writes configuration. The dashboard itself is started with webmux serve, which also starts the separate agents UI on its own port for mobile-friendly worktree chat.

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 plus the mobile-friendly agents UI on http://localhost:5112, with an actual worktree created through the CLI surface.

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 3

Start the dashboard

Launch the local app and open the UI in your browser.

webmux serve

Starts the main dashboard on http://localhost:5111 and the separate agents chat UI on http://localhost:5112 unless you override them with --port / --agents-port. The agents UI is primarily there for better mobile UX.

Step 4

Create your first worktree

Create a managed worktree from the CLI or from the dashboard UI.

webmux add my-change --prompt "ship the change"

webmux creates the worktree, allocates ports, runs lifecycle hooks, and starts the tmux session unless you pass --detach.

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>] [--agents-port <number>] [--app] [--debug]

Start the dashboard server for the current project.

Requires .webmux.yaml in the current directory.
Reads .env.local first, then .env, before launching.
Starts the main terminal dashboard on --port and the separate agents chat UI on --agents-port (default: port + 1).
The agents UI is primarily intended as a much better mobile experience for browsing worktrees and sending simple chat messages.
Uses PORT as a fallback when --port is omitted.
Use --app to open a Chromium-based app window after the backend starts.

init

webmux init

Interactive project setup for .webmux.yaml.

Must run inside a git repository.
Checks git, bun, python3, and tmux, enforces Bun >= 1.3.5, then offers Claude, Codex, or manual starter generation.
If gh is installed, warns when gh auth login is still needed.

service

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

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

Uses systemctl --user on Linux and launchctl on macOS.
install writes a service file that runs webmux serve --port ... from the git root.
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, merge, and send.
Add the output to your shell config with eval "$(webmux completion zsh)" or the bash equivalent.

Worktree commands

add

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

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

Branch is optional. When omitted, webmux uses auto_name if configured, otherwise it generates a change-<id> branch name.
Use --base to override workspace.mainBranch for a new worktree.
Repeat --env KEY=VALUE to override runtime env values for that worktree.
After creation, webmux switches tmux to the new worktree window unless you pass --detach.

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.

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.

send

webmux send <branch> <prompt> [--preamble <text>]
webmux send <branch> --prompt <text> [--preamble <text>]

Send a prompt to a running worktree agent through the local webmux server.

Use --prompt as an alternative to the positional prompt argument, but not both.
Use --preamble to prepend extra context before the prompt body.
This command posts to the current server port, so webmux serve must be running.

prune

webmux prune

Confirm and remove every managed worktree in the current project.

Prompts before deleting anything.
Removes only the current project's managed worktrees.

Configuration

.webmux.yaml is loaded from the git root and normalized into the final project config shape. .webmux.local.yaml can locally override worktreeRoot, profiles, lifecycle hooks, auto-pull, and selected integration toggles. 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
  autoPull:
    enabled: true
    intervalSeconds: 300

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
    systemPrompt: >
      You are working in ${WEBMUX_WORKTREE_PATH}
    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
        workingDir: frontend
        command: FRONTEND_PORT=$FRONTEND_PORT bun run dev

  sandbox:
    runtime: docker
    image: webmux-sandbox
    yolo: true
    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:
    autoRemoveOnMerge: true
    linkedRepos:
      - repo: myorg/related-service
        alias: related
        dir: ../related-service
  linear:
    enabled: true
    autoCreateWorktrees: true
    createTicketOption: true
    teamId: eng

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.
workspace.autoPull.enabled	boolean	no	false	Periodically fetches and fast-forwards workspace.mainBranch when enabled.
workspace.autoPull.intervalSeconds	number	no	300 (minimum 30)	Seconds between auto-pull attempts when autoPull is enabled.

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	no	host (or docker for a sandbox profile)	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	false	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[]	no	[agent, shell]	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	right (after the first pane)	Split direction relative to the previously created pane.
panes[].sizePct	number	no	-	Optional pane size percentage for the split.
panes[].focus	boolean	no	false	Marks the pane that should receive initial focus.
panes[].command	string	conditional	-	Startup command for command panes.
panes[].workingDir	string	no	-	Directory to cd into before running a command pane startup command.
panes[].cwd	repo \| worktree	no	worktree	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	hostPath	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.github.autoRemoveOnMerge	boolean	no	false	Automatically removes managed worktrees when their PRs merge.
integrations.linear.enabled	boolean	no	true	Turns Linear issue fetching on or off globally.
integrations.linear.autoCreateWorktrees	boolean	no	false	Automatically creates worktrees for eligible assigned Linear issues.
integrations.linear.createTicketOption	boolean	no	false	Shows the create-ticket action in the dashboard when Linear integration is enabled.
integrations.linear.teamId	string	no	-	Restricts Linear issue sync to a specific team id.

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 (if auto_name is set)	-	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, startup envs, and per-worktree port allocation.

Runtime environment reference

webmux writes runtime env files for managed worktrees and injects these variables into panes and lifecycle hooks, alongside startupEnvs, allocated service ports, and worktree-local .env.local values.

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.