Webmux

https://github.com/windmill-labs/webmux
Admin
Webmux is a web dashboard for managing parallel AI coding agents with git worktree lifecycle...
Tokens:36,487
Snippets:380
Trust Score:9.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install and Serve Webmux Dashboard

Source: https://context7.com/windmill-labs/webmux/llms.txt

Install Webmux globally using Bun and start the dashboard server. The server can be configured with a custom port or run in app-mode. Verbose logging is available with the --debug flag.

```bash
bun install -g webmux
```

```bash
webmux serve
```

```bash
webmux serve --port 6000
```

```bash
webmux serve --app
```

```bash
webmux serve --debug
```

--------------------------------

### Install and Initialize Webmux

Source: https://github.com/windmill-labs/webmux/blob/main/README.md

Installs webmux globally using bun, then initializes a project with a .webmux.yaml configuration file. Ensure prerequisites like tmux, python3, and bun are installed first.

```bash
sudo apt install tmux           # or: brew install tmux
sudo apt install python3        # or: brew install python
curl -fsSL https://bun.sh/install | bash

bun install -g webmux

cd /path/to/your/project
webmux init                         # creates .webmux.yaml

webmux serve                         # dashboard on http://localhost:5111
```

--------------------------------

### Example .webmux.yaml Configuration

Source: https://github.com/windmill-labs/webmux/blob/main/README.md

This example demonstrates a typical .webmux.yaml file, defining project name, workspace settings, services, development and sandbox profiles, GitHub integrations, and lifecycle hooks.

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

```

--------------------------------

### Lifecycle Hook Script Example

Source: https://context7.com/windmill-labs/webmux/llms.txt

Demonstrates accessing WebMux environment variables and emitting runtime events within a lifecycle hook script. Includes dependency installation and environment file configuration.

```bash
#!/usr/bin/env bash
# scripts/post-create.sh

# Available WEBMUX_* metadata
echo "Worktree ID: $WEBMUX_WORKTREE_ID"
echo "Branch:      $WEBMUX_BRANCH"
echo "Profile:     $WEBMUX_PROFILE"
echo "Agent:       $WEBMUX_AGENT"
echo "Project dir: $WEBMUX_PROJECT_DIR"
echo "Server port: $PORT"              # from services config

# Allocated service ports are injected as their portEnv names
echo "Backend port:  $PORT"
echo "Frontend port: $FRONTEND_PORT"

# Install dependencies in the new worktree
bun install

# Copy environment template
cp ../../.env.example .env.local
echo "PORT=$PORT" >> .env.local
echo "FRONTEND_PORT=$FRONTEND_PORT" >> .env.local

# Emit a runtime event back to the dashboard (optional)
CONTROL_TOKEN=$(cat .git/webmux-control-token)
curl -s -X POST "http://localhost:${WEBMUX_SERVER_PORT:-5111}/api/runtime/events" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CONTROL_TOKEN" \
  -d "{\"type\":\"post_create_done\",\"worktreeId\":\"$WEBMUX_WORKTREE_ID\"}" \
  > /dev/null
```

--------------------------------

### Initialize Webmux Configuration

Source: https://context7.com/windmill-labs/webmux/llms.txt

Run the interactive setup wizard to create a .webmux.yaml configuration file. This command prompts for project details and sets up sensible defaults.

```bash
cd /path/to/your/project
webmux init
```

--------------------------------

### Suggested control.env Contents

Source: https://github.com/windmill-labs/webmux/blob/main/docs/full-lifecycle-refactor-plan.md

Example of internal control values for communication with the webmux server.

```bash
WEBMUX_CONTROL_URL=http://127.0.0.1:5111
WEBMUX_CONTROL_TOKEN=...
WEBMUX_WORKTREE_ID=wt_01JQ8Q8QKQ0W8K5M6P2P9D4T7A
WEBMUX_BRANCH=feature/search-panel
```

--------------------------------

### Suggested runtime.env Contents

Source: https://github.com/windmill-labs/webmux/blob/main/docs/full-lifecycle-refactor-plan.md

Example of environment variables that should be exported for webmux-managed panes, hooks, and agents.

```bash
PORT=3010
FRONTEND_PORT=3010
PORT=5111
NODE_ENV=development
WEBMUX_BRANCH=feature/search-panel
WEBMUX_PROFILE=default
WEBMUX_AGENT=claude
WEBMUX_RUNTIME=host
```

--------------------------------

### Add New Worktree and Start Agent Session

Source: https://context7.com/windmill-labs/webmux/llms.txt

Create a new worktree, optionally with an auto-generated branch name from a prompt, custom base branch, or multi-agent setup. Supports Docker sandboxes and environment overrides. Use --detach to prevent switching to the new tmux session.

```bash
webmux add --prompt "Add OAuth2 login flow"
```

```bash
webmux add feature/oauth --agent claude --prompt "Implement OAuth2"
```

```bash
webmux add feature/existing-work --existing
```

```bash
webmux add --agent claude --agent codex --prompt "Refactor auth module"
```

```bash
webmux add --profile sandbox --base develop --env NODE_ENV=test --prompt "Fix SQL injection"
```

```bash
webmux add feature/bg-work --detach
```

--------------------------------

### Example .webmux.yaml Configuration

Source: https://github.com/windmill-labs/webmux/blob/main/docs/full-lifecycle-refactor-plan.md

Illustrates the structure of the `.webmux.yaml` configuration file, defining project name, workspace settings, multiple profiles with different runtimes and pane layouts, service definitions, startup environments, and integration settings.

```yaml
name: My Project

workspace:
  mainBranch: main
  worktreeRoot: __worktrees
  defaultAgent: claude

profiles:
  default:
    runtime: host
    systemPrompt: >
      You are working inside a project managed by webmux.
    envPassthrough:
      - GITHUB_TOKEN
    panes:
      - id: agent
        kind: agent
        focus: true
      - id: shell
        kind: shell
        split: right
        sizePct: 25

  sandbox:
    runtime: docker
    image: my-sandbox
    systemPrompt: >
      You are running inside a 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
      - id: shell
        kind: shell
        split: right
        sizePct: 25

services:
  - name: app
    portEnv: PORT
    portStart: 3000
    portStep: 10
    urlTemplate: http://127.0.0.1:${PORT}

startupEnvs:
  NODE_ENV: development

integrations:
  github:
    linkedRepos:
      - repo: org/other-repo
        alias: other
  linear:
    enabled: true

```

--------------------------------

### Example Pane Command with Environment Variable

Source: https://github.com/windmill-labs/webmux/blob/main/docs/full-lifecycle-refactor-plan.md

Demonstrates how a pane command can utilize an exported environment variable for dynamic port usage. Ensure the application respects exported environment variables.

```bash
npm run dev -- --port "$FRONTEND_PORT"
```

--------------------------------

### GET /api/config

Source: https://context7.com/windmill-labs/webmux/llms.txt

Returns the frontend-facing project configuration, including project name, service definitions, profile list, agent list, default selections, and feature flags.

```APIDOC
## REST API — `GET /api/config`

Returns the frontend-facing project configuration: project name, service definitions, profile list, agent list, default selections, and feature flags.

```bash
curl http://localhost:5111/api/config | jq .

# Response shape:
# {
#   "name": "My Project",
#   "mainBranch": "main",

```

--------------------------------

### Continue SDK Session from CLI

Source: https://github.com/windmill-labs/webmux/blob/main/docs/claude-code-session-continuation.md

Resume a conversation started in the Agents SDK by providing its session ID to the `claude` CLI using the `-r` flag.

```typescript
// 1. Start from the SDK
let sessionId: string;
for await (const msg of query({ prompt: "hello", options: { cwd: "/tmp" } })) {
  if (msg.type === "result") sessionId = msg.session_id;
}
```

```bash
# 2. Resume from the CLI
cd /tmp
claude -r "93bc0449-4ff1-474a-bc36-876654f935c2"
```

--------------------------------

### Fetch project configuration via REST API

Source: https://context7.com/windmill-labs/webmux/llms.txt

Retrieve frontend-facing project configuration details, including name, services, profiles, and feature flags, by making a GET request to the /api/config endpoint.

```bash
curl http://localhost:5111/api/config | jq .

# Response shape:
# {
#   "name": "My Project",
#   "mainBranch": "main",

```

--------------------------------

### Run Tests with Custom Isolated Tmux Config

Source: https://github.com/windmill-labs/webmux/blob/main/docs/autonomous-mode.md

This example demonstrates running tests with a custom tmux configuration for an isolated instance. It creates a temporary config file for 'destroy-unattached' option.

```bash
cfg="$(mktemp)" && printf '%s\n' 'set-option -g destroy-unattached on' > "$cfg" && WEBMUX_ISOLATED_TMUX_CONFIG="$cfg" bash scripts/run-with-isolated-tmux.sh bun test backend/src/__tests__/tmux-adapter.test.ts -t BunTmuxGateway; rm -f "$cfg"
```

--------------------------------

### Get Project Snapshot

Source: https://context7.com/windmill-labs/webmux/llms.txt

Retrieves the full project snapshot, including worktree status, PR data, and service health. Used for polling the main dashboard.

```bash
curl http://localhost:5111/api/project | jq .worktrees[0]
```

--------------------------------

### webmux update

Source: https://context7.com/windmill-labs/webmux/llms.txt

Updates webmux to the latest published version via `bun install -g webmux@latest`.

```APIDOC
## CLI — `webmux update`

Update webmux to the latest published version via `bun install -g webmux@latest`.

```bash
webmux update
```
```

--------------------------------

### Continue CLI Session from SDK

Source: https://github.com/windmill-labs/webmux/blob/main/docs/claude-code-session-continuation.md

Resume a conversation started in the Claude Code CLI by providing its session ID and working directory to the SDK's `query` function with the `resume` option.

```bash
# 1. Start a session in the CLI
cd /tmp
echo "remember the code word is BANANA" | claude -p --output-format json
# → session_id: "93bc0449-..."
```

```typescript
// 2. Continue from the SDK
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const msg of query({
  prompt: "What was the code word?",
  options: {
    resume: "93bc0449-4ff1-474a-bc36-876654f935c2",
    cwd: "/tmp",
  },
})) {
  if (msg.type === "result") {
    console.log(msg.result); // "BANANA"
    console.log(msg.session_id === "93bc0449-..."); // true — same session
  }
}
```

--------------------------------

### Add Initial Backend Files

Source: https://github.com/windmill-labs/webmux/blob/main/docs/full-lifecycle-implementation-steps.md

Creates placeholder files within the new backend directory structure. These files serve as entry points for different modules and services in the new architecture.

```text
backend/src/domain/config.ts
backend/src/domain/model.ts
backend/src/domain/events.ts
backend/src/domain/policies.ts
backend/src/adapters/fs.ts
backend/src/adapters/git.ts
backend/src/adapters/tmux.ts
backend/src/adapters/docker.ts
backend/src/adapters/hooks.ts
backend/src/services/project-runtime.ts
backend/src/services/worktree-service.ts
backend/src/services/session-service.ts
backend/src/services/agent-service.ts
backend/src/services/snapshot-service.ts
backend/src/services/notification-service.ts
backend/src/services/health-service.ts
backend/src/services/integration-service.ts
backend/src/api/routes.ts
backend/src/api/ws.ts
backend/src/cli/init.ts
backend/src/agentctl/main.ts
```

--------------------------------

### Project configuration with `.webmux.yaml`

Source: https://context7.com/windmill-labs/webmux/llms.txt

Define project-wide settings including name, workspace defaults, service ports, startup environments, and profile configurations.

```yaml
# Project display name in the dashboard
name: My Project

workspace:
  mainBranch: main              # base branch for new worktrees
  worktreeRoot: __worktrees     # relative dir where worktrees are created
  defaultAgent: claude          # "claude" | "codex" | custom agent id
  autoPull:
    enabled: true               # periodically fast-forward main branch
    intervalSeconds: 300        # minimum 30

services:
  - name: Backend
    portEnv: PORT               # env var injected into pane processes
    portStart: 5111             # base port for slot 0
    portStep: 10                # +10 per worktree slot
    urlTemplate: http://127.0.0.1:${PORT}   # optional UI link
  - name: Frontend
    portEnv: FRONTEND_PORT
    portStart: 5112
    portStep: 10
    urlTemplate: http://127.0.0.1:${FRONTEND_PORT}

startupEnvs:
  NODE_ENV: development
  FEATURE_FLAG: true

profiles:
  default:
    runtime: host               # "host" or "docker"
    yolo: false                 # --dangerously-skip-permissions / --yolo
    envPassthrough:             # host env vars forwarded to agent process
      - GITHUB_TOKEN
      - OPENAI_API_KEY
    systemPrompt: >
      You are working in a webmux-managed worktree.
      Backend: ${PORT}  Frontend: ${FRONTEND_PORT}
    panes:
      - id: agent
        kind: agent             # "agent" | "shell" | "command"
        focus: true
        split: right            # "right" | "bottom"
        sizePct: 65
        cwd: worktree           # "repo" | "worktree"
      - id: dev-server
        kind: command
        split: bottom
        sizePct: 35
        cwd: worktree
        command: bun run dev
        workingDir: frontend    # optional sub-directory for the command

  sandbox:
    runtime: docker
    yolo: true
    image: my-sandbox-image     # must have claude/codex on PATH
    envPassthrough:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
    systemPrompt: "You are in a sandbox container. Port: ${PORT}"
    mounts:
      - hostPath: ~/.codex
        guestPath: /root/.codex
        writable: true
    panes:
      - id: agent
        kind: agent
        focus: true

integrations:
  github:
    autoRemoveOnMerge: true     # remove worktrees when PR is merged
    linkedRepos:
      - repo: myorg/shared-lib
        alias: lib
        dir: ../shared-lib      # optional local path for pull-main
  linear:
    enabled: true
    autoCreateWorktrees: false  # auto-create worktrees for new Linear issues
    createTicketOption: true    # show "Create Linear ticket" in UI

auto_name:
  model: claude-3-5-haiku-latest  # claude-*, gemini-*, gpt-*, o* families
  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   # runs after worktree creation
  preRemove: scripts/pre-remove.sh     # runs before removal

```

--------------------------------

### Get Session ID from SDK

Source: https://github.com/windmill-labs/webmux/blob/main/docs/claude-code-session-continuation.md

The session ID is available on every `result` message when using the `@anthropic-ai/claude-agent-sdk`.

```typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const msg of query({ prompt: "hello", options: { cwd: "/tmp" } })) {
  if (msg.type === "result") {
    console.log(msg.session_id); // "93bc0449-..."
  }
}
```

--------------------------------

### Get Worktree Diff

Source: https://context7.com/windmill-labs/webmux/llms.txt

Retrieves the uncommitted diff, git status, and list of unpushed commits for a specified worktree.

```APIDOC
## GET /api/worktrees/:name/diff

### Description
Get the uncommitted diff, git status, and list of unpushed commits for a worktree.

### Method
GET

### Endpoint
/api/worktrees/:name/diff

### Response
#### Success Response (200)
- **uncommitted** (string) - The uncommitted diff content.
- **uncommittedTruncated** (boolean) - Indicates if the uncommitted diff was truncated.
- **gitStatus** (string) - The git status output.
- **unpushedCommits** (array) - A list of unpushed commits, each with 'hash' and 'message'.
```

--------------------------------

### Create a custom agent

Source: https://context7.com/windmill-labs/webmux/llms.txt

Creates a new custom agent. You must provide a `label` and `startCommand`. The `resumeCommand` is optional but recommended for agents that support session resumption. Built-in agents cannot be created.

```bash
curl -X POST http://localhost:5111/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "label": "My Agent",
    "startCommand": "my-agent --interactive",
    "resumeCommand": "my-agent --resume ${SESSION_ID}"
  }'
```

--------------------------------

### Get Session Info using SDK

Source: https://github.com/windmill-labs/webmux/blob/main/docs/claude-code-session-continuation.md

Retrieve detailed information about a specific session using its ID and the `getSessionInfo` function.

```typescript
import { getSessionInfo } from "@anthropic-ai/claude-agent-sdk";

const info = await getSessionInfo("93bc0449-...", { dir: "/tmp" });
// { sessionId, summary, lastModified, firstPrompt, gitBranch, cwd, createdAt, ... }
```

--------------------------------

### Get Session ID from CLI

Source: https://github.com/windmill-labs/webmux/blob/main/docs/claude-code-session-continuation.md

Use `--output-format json` with the `claude` CLI in print mode to retrieve the session ID from the structured output.

```bash
echo "hello" | claude -p --output-format json
```

```json
{
  "type": "result",
  "session_id": "93bc0449-4ff1-474a-bc36-876654f935c2",
  "result": "..."
}
```

--------------------------------

### Local configuration overlay with `.webmux.local.yaml`

Source: https://context7.com/windmill-labs/webmux/llms.txt

Override or extend project-level settings with local-only configurations. Profile definitions are additive, and lifecycle hook commands are appended.

```yaml
# .webmux.local.yaml — not committed to version control
profiles:
  my-local-profile:
    runtime: host
    yolo: true
    panes:
      - id: agent
        kind: agent
        focus: true

lifecycleHooks:
  postCreate: scripts/local-post-create.sh

```

--------------------------------

### Configuration - .webmux.local.yaml

Source: https://context7.com/windmill-labs/webmux/llms.txt

Optional local-only overlay for configuration. Profile definitions are additive, and lifecycle hook commands are appended.

```APIDOC
## Configuration — `.webmux.local.yaml`

Optional local-only overlay. Profile definitions are additive (conflicting profile names replace the project-level definition). Lifecycle hook commands are appended after the project-level command.

```yaml
# .webmux.local.yaml — not committed to version control
profiles:
  my-local-profile:
    runtime: host
    yolo: true
    panes:
      - id: agent
        kind: agent
        focus: true

lifecycleHooks:
  postCreate: scripts/local-post-create.sh
```
```

--------------------------------

### Configuration - .webmux.yaml

Source: https://context7.com/windmill-labs/webmux/llms.txt

The project configuration file. All keys are optional unless noted.

```APIDOC
## Configuration — `.webmux.yaml`

The project configuration file. All keys are optional unless noted.

```yaml
# Project display name in the dashboard
name: My Project

workspace:
  mainBranch: main              # base branch for new worktrees
  worktreeRoot: __worktrees     # relative dir where worktrees are created
  defaultAgent: claude          # "claude" | "codex" | custom agent id
  autoPull:
    enabled: true               # periodically fast-forward main branch
    intervalSeconds: 300        # minimum 30

services:
  - name: Backend
    portEnv: PORT               # env var injected into pane processes
    portStart: 5111             # base port for slot 0
    portStep: 10                # +10 per worktree slot
    urlTemplate: http://127.0.0.1:${PORT}   # optional UI link
  - name: Frontend
    portEnv: FRONTEND_PORT
    portStart: 5112
    portStep: 10
    urlTemplate: http://127.0.0.1:${FRONTEND_PORT}

startupEnvs:
  NODE_ENV: development
  FEATURE_FLAG: true

profiles:
  default:
    runtime: host               # "host" or "docker"
    yolo: false                 # --dangerously-skip-permissions / --yolo
    envPassthrough:             # host env vars forwarded to agent process
      - GITHUB_TOKEN
      - OPENAI_API_KEY
    systemPrompt: >
      You are working in a webmux-managed worktree.
      Backend: ${PORT}  Frontend: ${FRONTEND_PORT}
    panes:
      - id: agent
        kind: agent             # "agent" | "shell" | "command"
        focus: true
        split: right            # "right" | "bottom"
        sizePct: 65
        cwd: worktree           # "repo" | "worktree"
      - id: dev-server
        kind: command
        split: bottom
        sizePct: 35
        cwd: worktree
        command: bun run dev
        workingDir: frontend    # optional sub-directory for the command

  sandbox:
    runtime: docker
    yolo: true
    image: my-sandbox-image     # must have claude/codex on PATH
    envPassthrough:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
    systemPrompt: "You are in a sandbox container. Port: ${PORT}"
    mounts:
      - hostPath: ~/.codex
        guestPath: /root/.codex
        writable: true
    panes:
      - id: agent
        kind: agent
        focus: true

integrations:
  github:
    autoRemoveOnMerge: true     # remove worktrees when PR is merged
    linkedRepos:
      - repo: myorg/shared-lib
        alias: lib
        dir: ../shared-lib      # optional local path for pull-main
  linear:
    enabled: true
    autoCreateWorktrees: false  # auto-create worktrees for new Linear issues
    createTicketOption: true    # show "Create Linear ticket" in UI

auto_name:
  model: claude-3-5-haiku-latest  # claude-*, gemini-*, gpt-*, o* families
  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   # runs after worktree creation
  preRemove: scripts/pre-remove.sh     # runs before removal
```
```

--------------------------------

### Get Session Messages using SDK

Source: https://github.com/windmill-labs/webmux/blob/main/docs/claude-code-session-continuation.md

Fetch all messages from a specific session using its ID and the `getSessionMessages` function. Iterate through the messages to access their role and content.

```typescript
import { getSessionMessages } from "@anthropic-ai/claude-agent-sdk";

const messages = await getSessionMessages("93bc0449-...", { dir: "/tmp" });
for (const m of messages) {
  console.log(m.message.role, m.message.content);
}
```

--------------------------------

### Create New Backend Directories

Source: https://github.com/windmill-labs/webmux/blob/main/docs/full-lifecycle-implementation-steps.md

Defines the directory structure for the new backend architecture. This phase focuses on establishing a clear organizational layout for the codebase.

```text
backend/src/
  domain/
  services/
  adapters/
  api/
  cli/
  agentctl/
```

--------------------------------

### Get worktree diff and status

Source: https://context7.com/windmill-labs/webmux/llms.txt

Retrieves the uncommitted changes, git status, and a list of unpushed commits for a given worktree. This is helpful for reviewing changes before committing or pushing.

```bash
curl http://localhost:5111/api/worktrees/feature%2Foauth/diff | jq .
```

--------------------------------

### Fetch failed CI job logs

Source: https://context7.com/windmill-labs/webmux/llms.txt

Fetches the logs for failed CI jobs associated with a specific GitHub Actions run ID. This requires the `gh` CLI to be installed and authenticated.

```bash
curl http://localhost:5111/api/ci-logs/12345678 | jq .logs
```

--------------------------------

### Suggested Backend Repository Structure

Source: https://github.com/windmill-labs/webmux/blob/main/docs/full-lifecycle-refactor-plan.md

Illustrates a proposed directory structure for the WebMux backend. This organization aims to separate concerns into domain, services, adapters, API, and CLI layers.

```text
backend/src/
  domain/
    config.ts
    model.ts
    events.ts
    policies.ts
  services/
    project-runtime.ts
    worktree-service.ts
    session-service.ts
    agent-service.ts
    health-service.ts
    integration-service.ts
    notification-service.ts
    snapshot-service.ts
  adapters/
    git.ts
    tmux.ts
    docker.ts
    github.ts
    linear.ts
    fs.ts
    hooks.ts
  api/
    http.ts
    ws.ts
    routes.ts
  cli/
    init.ts
    doctor.ts
    hooks.ts
    server.ts
  agentctl/
    main.ts
```

--------------------------------

### List all agents

Source: https://context7.com/windmill-labs/webmux/llms.txt

Lists all available agents, including both built-in agents (like `claude`, `codex`) and any custom agents that have been created. This provides an overview of all agent configurations.

```bash
curl http://localhost:5111/api/agents | jq .agents
```

--------------------------------

### Create New Worktree

Source: https://context7.com/windmill-labs/webmux/llms.txt

Creates new worktrees with various options including new or existing branches, multi-agent pairing, sandbox profiles, environment overrides, and Linear ticket creation.

```bash
# New branch with auto-generated name from prompt
curl -X POST http://localhost:5111/api/worktrees \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Add rate limiting to the API", "agent": "claude" }'
```

```bash
# Explicit branch with sandbox profile
curl -X POST http://localhost:5111/api/worktrees \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "feature/rate-limit",
    "profile": "sandbox",
    "agent": "codex",
    "prompt": "Implement token bucket rate limiting",
    "envOverrides": { "RATE_LIMIT": "100" }
  }'
```

```bash
# Multi-agent paired worktrees
curl -X POST http://localhost:5111/api/worktrees \
  -H "Content-Type: application/json" \
  -d '{
    "agents": ["claude", "codex"],
    "prompt": "Migrate database to PostgreSQL"
  }'
```

```bash
# Use an existing remote branch
curl -X POST http://localhost:5111/api/worktrees \
  -H "Content-Type: application/json" \
  -d '{ "branch": "feature/existing", "mode": "existing" }'
```

```bash
# Create and also open a Linear ticket
curl -X POST http://localhost:5111/api/worktrees \
  -H "Content-Type: application/json" \
  -d '{
    "createLinearTicket": true,
    "prompt": "Fix memory leak in worker pool",
    "linearTitle": "Fix memory leak in worker pool"
  }'
```

--------------------------------

### Get Project Snapshot

Source: https://context7.com/windmill-labs/webmux/llms.txt

Retrieves the complete project snapshot, including worktree status, PR data, CI checks, service health, and Linear issue links. This is used by the main dashboard for polling.

```APIDOC
## GET /api/project

### Description
Returns the full project snapshot: worktree list with status, PR data, CI checks, service health, notifications, and Linear issue links. Used by the main dashboard for polling.

### Method
GET

### Endpoint
/api/project

### Response
#### Success Response (200)
- **worktrees** (array) - List of worktree objects, each containing details like branch, path, status, services, PRs, and Linear issue links.

### Response Example
```json
{
  "worktrees": [
    {
      "branch": "feature/oauth",
      "baseBranch": "main",
      "path": "/home/user/myapp/__worktrees/feature-oauth",
      "archived": false,
      "profile": "default",
      "agentName": "claude",
      "agentLabel": "Claude",
      "mux": true,
      "dirty": true,
      "unpushed": false,
      "paneCount": 2,
      "status": "running",
      "elapsed": "5m",
      "services": [
        { "name": "Backend", "port": 5121, "running": true, "url": "http://127.0.0.1:5121" }
      ],
      "prs": [
        { "repo": "myorg/myapp", "number": 42, "state": "open", "ciStatus": "pending", "ciChecks": [], "comments": [] }
      ],
      "linearIssue": {
        "identifier": "ENG-123",
        "url": "https://linear.app/",
        "state": {
          "name": "In Progress",
          "color": "#f59e0b",
          "type": "started"
        }
      },
      "creation": null
    }
  ]
}
```
```

--------------------------------

### Enumerate Worktrees using Git Porcelain

Source: https://github.com/windmill-labs/webmux/blob/main/docs/full-lifecycle-implementation-steps.md

Implements worktree discovery by parsing the output of `git worktree list --porcelain`. This allows the system to identify and manage all associated worktrees within a repository.

```typescript
async listWorktrees(repoRoot: string): Promise<WorktreeMeta[]> {
  const { stdout } = await execa("git", ["worktree", "list", "--porcelain"], {
    cwd: repoRoot,
  });
  return parseGitWorktreeList(stdout);
}
```

--------------------------------

### Generate shell completion scripts with `webmux completion`

Source: https://context7.com/windmill-labs/webmux/llms.txt

Generate tab-completion scripts for Zsh and Bash to improve command-line usability. Source the generated file to enable completions.

```bash
# Zsh
webmux completion zsh >> ~/.zshrc
source ~/.zshrc
```

```bash
# Bash
webmux completion bash >> ~/.bashrc
source ~/.bashrc
```

--------------------------------

### Send message to worktree with preamble

Source: https://context7.com/windmill-labs/webmux/llms.txt

Use this endpoint to send a message to a specific worktree, prepending a preamble to the message. The preamble is useful for providing context, such as a PR reviewer comment.

```bash
curl -X POST http://localhost:5111/api/worktrees/feature%2Foauth/send \
  -H "Content-Type: application/json" \
  -d '{ "text": "Fix the issue on line 42", "preamble": "PR reviewer comment:" }'
```

--------------------------------

### Run Webmux Serve with Isolated Tmux

Source: https://github.com/windmill-labs/webmux/blob/main/docs/autonomous-mode.md

Execute the Webmux server using an isolated tmux instance via this script. This is useful for testing server behavior in a controlled environment.

```bash
bash scripts/run-with-isolated-tmux.sh bun bin/webmux.js serve --port 6121
```

--------------------------------

### Fork Session (SDK)

Source: https://github.com/windmill-labs/webmux/blob/main/docs/claude-code-session-continuation.md

Create a new, independent session that branches off from an existing one by setting `forkSession: true` in the SDK options. The original session remains unchanged.

```typescript
query({
  prompt: "try a different approach",
  options: {
    resume: "93bc0449-...",
    forkSession: true,
    cwd: "/tmp",
  },
});
```

--------------------------------

### Open and Close Worktree Sessions

Source: https://context7.com/windmill-labs/webmux/llms.txt

Manage tmux sessions for worktrees. 'open' creates a new tmux window and switches to it, while 'close' kills the tmux window but preserves the worktree directory.

```bash
webmux open feature/oauth
```

```bash
webmux close feature/oauth
```

--------------------------------

### webmux completion

Source: https://context7.com/windmill-labs/webmux/llms.txt

Generates shell tab-completion scripts for bash or zsh.

```APIDOC
## CLI — `webmux completion`

Generate shell tab-completion scripts for bash or zsh.

```bash
# Zsh
webmux completion zsh >> ~/.zshrc
source ~/.zshrc

# Bash
webmux completion bash >> ~/.bashrc
source ~/.bashrc
```
```

--------------------------------

### List available branches

Source: https://context7.com/windmill-labs/webmux/llms.txt

Lists all available local and optionally remote branches. This endpoint is used to populate the new-worktree picker, allowing users to select a branch when creating a new worktree.

```bash
curl "http://localhost:5111/api/branches?includeRemote=true" | jq .
```

--------------------------------

### Fork Session (CLI)

Source: https://github.com/windmill-labs/webmux/blob/main/docs/claude-code-session-continuation.md

Use the `--fork-session` flag with the `-r` option in the `claude` CLI to create a new session that branches off from a specified existing session.

```bash
claude -r "93bc0449-..." --fork-session
```

--------------------------------

### List Sessions using SDK

Source: https://github.com/windmill-labs/webmux/blob/main/docs/claude-code-session-continuation.md

Use the `listSessions` function from the SDK to retrieve a list of recent sessions within a specified directory.

```typescript
import { listSessions } from "@anthropic-ai/claude-agent-sdk";

const sessions = await listSessions({ dir: "/path/to/project", limit: 10 });
// [{ sessionId, summary, lastModified, fileSize, firstPrompt, gitBranch, cwd, createdAt }]
```

--------------------------------

### Connect to Agent Chat WebSocket

Source: https://context7.com/windmill-labs/webmux/llms.txt

Establishes a WebSocket connection to stream conversation events. Handles snapshot, messageDelta, and error events.

```javascript
const ws = new WebSocket("ws://localhost:5111/ws/agents/worktrees/feature%2Foauth");

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case "snapshot":
      // Full conversation state: all messages, running flag, worktree summary
      console.log("Messages:", msg.data.conversation.messages.length);
      console.log("Running:", msg.data.conversation.running);
      break;

    case "messageDelta":
      // Streaming token delta from Codex app server
      // { conversationId, turnId, itemId, delta: "partial text..." }
      process.stdout.write(msg.delta);
      break;

    case "error":
      console.error("Conversation error:", msg.message);
      ws.close();
      break;
  }
};

ws.onerror = (err) => console.error("WebSocket error:", err);
ws.onclose = (event) => console.log("Closed:", event.code, event.reason);
```

--------------------------------

### List Worktrees

Source: https://context7.com/windmill-labs/webmux/llms.txt

Display a list of worktrees and their status. Options include showing all worktrees (including archived), only archived worktrees, or filtering by search terms like branch name, profile, or agent.

```bash
webmux list
```

```bash
webmux list --all
```

```bash
webmux list --archived
```

```bash
webmux list --search oauth
```

--------------------------------

### Create Worktrees

Source: https://context7.com/windmill-labs/webmux/llms.txt

Creates one or more new worktrees. This endpoint supports creating new branches with auto-generated names, using existing branches, setting up multi-agent paired worktrees, utilizing Docker sandbox profiles, overriding environment variables, and optionally creating Linear tickets.

```APIDOC
## POST /api/worktrees

### Description
Create one or more new worktrees. Supports new branches, existing branches, multi-agent paired worktrees, Docker sandbox profiles, env overrides, and optional Linear ticket creation.

### Method
POST

### Endpoint
/api/worktrees

### Parameters
#### Request Body
- **prompt** (string) - Optional - A prompt to guide the agent in creating a new branch and its initial commit.
- **branch** (string) - Optional - The name of the branch to create. If not provided and `prompt` is given, a name will be auto-generated.
- **mode** (string) - Optional - Specifies how to handle the branch. Use 'existing' to use a branch that already exists locally or remotely.
- **profile** (string) - Optional - The name of a sandbox profile to use for the worktree.
- **agent** (string) - Optional - The ID of the agent to use for this worktree.
- **agents** (array of strings) - Optional - A list of agent IDs to use for paired worktrees.
- **envOverrides** (object) - Optional - Key-value pairs for environment variable overrides.
- **createLinearTicket** (boolean) - Optional - If true, a Linear ticket will be created for this worktree.
- **linearTitle** (string) - Optional - The title for the Linear ticket if `createLinearTicket` is true.

### Request Example
```json
# New branch with auto-generated name from prompt
{
  "prompt": "Add rate limiting to the API",
  "agent": "claude"
}

# Explicit branch with sandbox profile
{
  "branch": "feature/rate-limit",
  "profile": "sandbox",
  "agent": "codex",
  "prompt": "Implement token bucket rate limiting",
  "envOverrides": {
    "RATE_LIMIT": "100"
  }
}

# Multi-agent paired worktrees
{
  "agents": ["claude", "codex"],
  "prompt": "Migrate database to PostgreSQL"
}

# Use an existing remote branch
{
  "branch": "feature/existing",
  "mode": "existing"
}

# Create and also open a Linear ticket
{
  "createLinearTicket": true,
  "prompt": "Fix memory leak in worker pool",
  "linearTitle": "Fix memory leak in worker pool"
}
```

### Response
#### Success Response (201)
- **primaryBranch** (string) - The name of the primary branch created.
- **branches** (array of strings) - A list of all branches created for this worktree.

#### Response Example
```json
{ "primaryBranch": "feature/rate-limit", "branches": ["feature/rate-limit"] }
```
```

--------------------------------

### Open Worktree

Source: https://context7.com/windmill-labs/webmux/llms.txt

Opens or re-opens a closed worktree, establishing a new tmux session window for it.

```bash
curl -X POST http://localhost:5111/api/worktrees/feature%2Foauth/open
```
Tokens:
Raw