# windmill-labs/webmux architecture

> Architecture diagram of the GitHub repository windmill-labs/webmux, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/windmill-labs/webmux
- Repository: https://github.com/windmill-labs/webmux

## Overview

webmux is a multi-project dashboard and CLI for creating and managing AI-agent Git worktrees, sessions, terminals, and related development workflows. The main user flow runs from the dashboard through the backend to worktree and agent operations, then streams status and output back to the UI. The README documents PR/CI, service health, Docker sandboxing, Linear, and mobile chat as additional product branches. Some implementation wiring is not shown in the sampled excerpts, so uncertain links are omitted.

Main entry points: [`backend/src/server.ts`](https://github.com/windmill-labs/webmux/blob/main/backend/src/server.ts) (HTTP and WS server), [`frontend/src/lib/api.ts`](https://github.com/windmill-labs/webmux/blob/main/frontend/src/lib/api.ts) (API client), [`backend/src/adapters/git.ts`](https://github.com/windmill-labs/webmux/blob/main/backend/src/adapters/git.ts) (Git worktrees), [`backend/src/runtime.ts`](https://github.com/windmill-labs/webmux/blob/main/backend/src/runtime.ts) (Project runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard interfaces"]
  node_browser["Dashboard UI<br/>[App.svelte]"]
  node_mobile["Mobile chat UI"]
  node_api["API client<br/>[api.ts]"]
end

subgraph group_backend["Backend orchestration"]
  node_contract["API contract<br/>[contract.ts]"]
  node_server["HTTP and WS server<br/>[server.ts]"]
  node_runtime["Project runtime<br/>[runtime.ts]"]
  node_config["Project configuration<br/>[config.ts]"]
  node_health["Service health<br/>[project-runtime.ts]"]
  node_pr["PR and CI status<br/>[pr-service.ts]"]
  node_linear["Linear workflows<br/>[linear-service.ts]"]
end

subgraph group_worktrees["Worktree and agent runtime"]
  node_worktree["Worktree operations"]
  node_creation["Worktree creation"]
  node_lifecycle["Worktree lifecycle"]
  node_agents["Agent runtime<br/>[agent-runtime.ts]"]
  node_terminal["Terminal streaming<br/>[terminal.ts]"]
  node_codexlog["Conversation history"]
end

subgraph group_integrations["External integrations"]
  node_git["Git worktrees<br/>[git.ts]"]
  node_tmux["tmux sessions<br/>[tmux.ts]"]
  node_github["GitHub CLI"]
  node_linearapi["Linear API"]
  node_sandbox["Docker sandbox<br/>[docker.ts]"]
end

subgraph group_projects["Projects and sessions"]
  node_projectmgr["Project manager<br/>[project-manager.ts]"]
  node_registry[("Projects registry")]
  node_session["Session layout<br/>[session-service.ts]"]
end

node_user(("Developer"))

node_user -->|"uses"| node_browser
node_user -->|"uses"| node_mobile
node_browser -->|"requests"| node_api
node_mobile -->|"requests"| node_api
node_api -->|"calls routes"| node_contract
node_api -->|"sends API requests"| node_server
node_server -->|"handles requests"| node_runtime
node_server -->|"fetches PR states"| node_pr
node_pr -.->|"queries"| node_github
node_server -->|"builds issue seed"| node_linear
node_linear -.->|"reads and posts"| node_linearapi
node_projectmgr -->|"loads and persists projects"| node_registry
node_projectmgr -->|"creates project runtime"| node_runtime
node_runtime -->|"loads settings"| node_config
node_worktree -->|"manages worktrees"| node_git
node_creation -->|"creates worktrees"| node_git
node_lifecycle -->|"updates worktrees"| node_git
node_session -->|"creates pane layout"| node_tmux
node_agents -->|"runs in sessions"| node_tmux
node_server -->|"writes terminal input"| node_terminal
node_server -->|"archives worktrees"| node_lifecycle
node_health -->|"checks worktree services"| node_git
node_sandbox -.->|"hosts isolated runs"| node_agents
node_codexlog -->|"parses session logs"| node_agents

click node_browser "https://github.com/windmill-labs/webmux/blob/main/frontend/src/App.svelte"
click node_mobile "https://github.com/windmill-labs/webmux/blob/main/frontend/src/lib/MobileChatSurface.svelte"
click node_api "https://github.com/windmill-labs/webmux/blob/main/frontend/src/lib/api.ts"
click node_contract "https://github.com/windmill-labs/webmux/blob/main/packages/api-contract/src/contract.ts"
click node_server "https://github.com/windmill-labs/webmux/blob/main/backend/src/server.ts"
click node_runtime "https://github.com/windmill-labs/webmux/blob/main/backend/src/runtime.ts"
click node_config "https://github.com/windmill-labs/webmux/blob/main/backend/src/domain/config.ts"
click node_projectmgr "https://github.com/windmill-labs/webmux/blob/main/backend/src/services/project-manager.ts"
click node_registry "https://github.com/windmill-labs/webmux/blob/main/backend/src/adapters/projects-registry.ts"
click node_worktree "https://github.com/windmill-labs/webmux/blob/main/backend/src/services/worktree-service.ts"
click node_creation "https://github.com/windmill-labs/webmux/blob/main/backend/src/services/worktree-creation-service.ts"
click node_lifecycle "https://github.com/windmill-labs/webmux/blob/main/backend/src/services/lifecycle-service.ts"
click node_git "https://github.com/windmill-labs/webmux/blob/main/backend/src/adapters/git.ts"
click node_session "https://github.com/windmill-labs/webmux/blob/main/backend/src/services/session-service.ts"
click node_tmux "https://github.com/windmill-labs/webmux/blob/main/backend/src/adapters/tmux.ts"
click node_agents "https://github.com/windmill-labs/webmux/blob/main/backend/src/adapters/agent-runtime.ts"
click node_terminal "https://github.com/windmill-labs/webmux/blob/main/backend/src/adapters/terminal.ts"
click node_health "https://github.com/windmill-labs/webmux/blob/main/backend/src/services/project-runtime.ts"
click node_pr "https://github.com/windmill-labs/webmux/blob/main/backend/src/services/pr-service.ts"
click node_linear "https://github.com/windmill-labs/webmux/blob/main/backend/src/services/linear-service.ts"
click node_sandbox "https://github.com/windmill-labs/webmux/blob/main/backend/src/adapters/docker.ts"
click node_codexlog "https://github.com/windmill-labs/webmux/blob/main/backend/src/services/codex-session-log-service.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_mobile,node_api toneBlue
class node_contract,node_server,node_runtime,node_config,node_health,node_pr,node_linear toneAmber
class node_worktree,node_creation,node_lifecycle,node_agents,node_terminal,node_codexlog toneMint
class node_git,node_tmux,node_github,node_linearapi,node_sandbox toneRose
class node_projectmgr,node_registry,node_session,node_user toneIndigo
```

## Components

### Dashboard interfaces

- [Dashboard UI](https://github.com/windmill-labs/webmux/blob/main/frontend/src/App.svelte): `frontend/src/App.svelte`
- [Mobile chat UI](https://github.com/windmill-labs/webmux/blob/main/frontend/src/lib/MobileChatSurface.svelte): `frontend/src/lib/MobileChatSurface.svelte`
- [API client](https://github.com/windmill-labs/webmux/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Backend orchestration

- [API contract](https://github.com/windmill-labs/webmux/blob/main/packages/api-contract/src/contract.ts): `packages/api-contract/src/contract.ts`
- [HTTP and WS server](https://github.com/windmill-labs/webmux/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Project runtime](https://github.com/windmill-labs/webmux/blob/main/backend/src/runtime.ts): `backend/src/runtime.ts`
- [Project configuration](https://github.com/windmill-labs/webmux/blob/main/backend/src/domain/config.ts): `backend/src/domain/config.ts`
- [Service health](https://github.com/windmill-labs/webmux/blob/main/backend/src/services/project-runtime.ts): `backend/src/services/project-runtime.ts`
- [PR and CI status](https://github.com/windmill-labs/webmux/blob/main/backend/src/services/pr-service.ts): `backend/src/services/pr-service.ts`
- [Linear workflows](https://github.com/windmill-labs/webmux/blob/main/backend/src/services/linear-service.ts): `backend/src/services/linear-service.ts`

### Worktree and agent runtime

- [Worktree operations](https://github.com/windmill-labs/webmux/blob/main/backend/src/services/worktree-service.ts): `backend/src/services/worktree-service.ts`
- [Worktree creation](https://github.com/windmill-labs/webmux/blob/main/backend/src/services/worktree-creation-service.ts): `backend/src/services/worktree-creation-service.ts`
- [Worktree lifecycle](https://github.com/windmill-labs/webmux/blob/main/backend/src/services/lifecycle-service.ts): `backend/src/services/lifecycle-service.ts`
- [Agent runtime](https://github.com/windmill-labs/webmux/blob/main/backend/src/adapters/agent-runtime.ts): `backend/src/adapters/agent-runtime.ts`
- [Terminal streaming](https://github.com/windmill-labs/webmux/blob/main/backend/src/adapters/terminal.ts): `backend/src/adapters/terminal.ts`
- [Conversation history](https://github.com/windmill-labs/webmux/blob/main/backend/src/services/codex-session-log-service.ts): `backend/src/services/codex-session-log-service.ts`

### External integrations

- [Git worktrees](https://github.com/windmill-labs/webmux/blob/main/backend/src/adapters/git.ts): `backend/src/adapters/git.ts`
- [tmux sessions](https://github.com/windmill-labs/webmux/blob/main/backend/src/adapters/tmux.ts): `backend/src/adapters/tmux.ts`
- **GitHub CLI**
- **Linear API**
- [Docker sandbox](https://github.com/windmill-labs/webmux/blob/main/backend/src/adapters/docker.ts): `backend/src/adapters/docker.ts`

### Projects and sessions

- [Project manager](https://github.com/windmill-labs/webmux/blob/main/backend/src/services/project-manager.ts): `backend/src/services/project-manager.ts`
- [Projects registry](https://github.com/windmill-labs/webmux/blob/main/backend/src/adapters/projects-registry.ts): `backend/src/adapters/projects-registry.ts`
- [Session layout](https://github.com/windmill-labs/webmux/blob/main/backend/src/services/session-service.ts): `backend/src/services/session-service.ts`

### Other components

- **Developer**

## Connections

- Developer → Dashboard UI: uses
- Developer → Mobile chat UI: uses
- Dashboard UI → API client: requests
- Mobile chat UI → API client: requests
- API client → API contract: calls routes
- API client → HTTP and WS server: sends API requests
- HTTP and WS server → Project runtime: handles requests
- HTTP and WS server → PR and CI status: fetches PR states
- PR and CI status → GitHub CLI: queries
- HTTP and WS server → Linear workflows: builds issue seed
- Linear workflows → Linear API: reads and posts
- Project manager → Projects registry: loads and persists projects
- Project manager → Project runtime: creates project runtime
- Project runtime → Project configuration: loads settings
- Worktree operations → Git worktrees: manages worktrees
- Worktree creation → Git worktrees: creates worktrees
- Worktree lifecycle → Git worktrees: updates worktrees
- Session layout → tmux sessions: creates pane layout
- Agent runtime → tmux sessions: runs in sessions
- HTTP and WS server → Terminal streaming: writes terminal input
- HTTP and WS server → Worktree lifecycle: archives worktrees
- Service health → Git worktrees: checks worktree services
- Docker sandbox → Agent runtime: hosts isolated runs
- Conversation history → Agent runtime: parses session logs