# excitedjs/dreamux architecture

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

- Interactive diagram: https://gitdiagram.com/excitedjs/dreamux
- Repository: https://github.com/excitedjs/dreamux

## Overview

Dreamux is a local dispatcher host: `dreamux serve` loads provider-backed configuration, starts multiple dispatchers in one Node process, and connects agent runtimes with channel providers and Dreamux-owned MCP surfaces. A user message enters through a channel, reaches dispatcher services through the shared command port, and is handled by its configured agent runtime; results can return through the channel. Teams, teammates, scheduling, workflows, and administration are major host capabilities. The graph reflects README and sampled source; unsampled subsystem wiring is omitted where ownership could not be verified.

Main entry points: [`packages/dreamux/src/service/dispatcher-service/index.ts`](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/dispatcher-service/index.ts) (Dispatcher services), [`packages/dreamux/src/server.ts`](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/server.ts) (Dreamux server), [`packages/dreamux/src/cli/server.ts`](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/cli/server.ts) (Serve CLI), [`packages/dreamux/src/service/index.ts`](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/index.ts) (Dispatcher collection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host lifecycle"]
  node_cli["Serve CLI<br/>[server.ts]"]
  node_config["Config loader<br/>[config.ts]"]
  node_registry["Provider registry<br/>[registry.ts]"]
  node_server["Dreamux server<br/>[server.ts]"]
  node_admin["Admin socket<br/>[client.ts]"]
end

subgraph group_dispatch["Dispatcher runtime"]
  node_dispatchers["Dispatcher collection<br/>[index.ts]"]
  node_commands["Command port<br/>[port.ts]"]
  node_dispatcher["Dispatcher services<br/>[index.ts]"]
  node_runtimecatalog["Runtime catalog<br/>[catalog.ts]"]
  node_codex["Codex runtime<br/>[runtime.ts]"]
  node_claude["Claude runtime<br/>[runtime.ts]"]
end

subgraph group_channels["Channel integrations"]
  node_channelcatalog["Channel catalog<br/>[catalog.ts]"]
  node_feishu["Feishu channel<br/>[feishu-channel.ts]"]
  node_transport["Feishu transport<br/>[feishu.ts]"]
end

subgraph group_mcp["MCP surfaces"]
  node_mcpserver["MCP server<br/>[server.ts]"]
  node_mcpcatalog["MCP catalog<br/>[catalog.ts]"]
end

subgraph group_state["State and automation"]
  node_teams["Team services<br/>[index.ts]"]
  node_teammates["Teammate services<br/>[index.ts]"]
  node_teamstore[("Team store<br/>[store.ts]")]
  node_scheduler["Scheduler<br/>[service.ts]"]
  node_workflows["Workflow service<br/>[index.ts]"]
  node_worktrees["Worktree manager<br/>[manager.ts]"]
end

node_operator(("Operator"))
node_admincaller(("Admin caller"))
node_channeluser(("Channel user"))
node_mcpclient(("MCP client"))

node_operator -->|"starts"| node_cli
node_cli -->|"seeds providers"| node_registry
node_cli -->|"loads config"| node_config
node_config -->|"loads implementations"| node_registry
node_cli -->|"starts"| node_server
node_server -->|"boots"| node_dispatchers
node_server -->|"composes"| node_commands
node_server -->|"owns IPC"| node_admin
node_admincaller -->|"sends commands"| node_admin
node_dispatchers -->|"runs"| node_dispatcher
node_dispatchers -->|"resolves providers"| node_runtimecatalog
node_dispatchers -->|"resolves providers"| node_channelcatalog
node_runtimecatalog -->|"selects"| node_codex
node_runtimecatalog -->|"selects"| node_claude
node_channelcatalog -->|"selects"| node_feishu
node_channeluser -->|"sends message"| node_transport
node_feishu -->|"uses I/O"| node_transport
node_feishu -->|"invokes"| node_commands
node_commands -->|"dispatches"| node_dispatcher
node_dispatcher -->|"manages teams"| node_teams
node_dispatcher -->|"manages teammates"| node_teammates
node_dispatcher -->|"schedules work"| node_scheduler
node_dispatcher -->|"runs workflows"| node_workflows
node_teammates -->|"manages workspaces"| node_worktrees
node_teams -->|"persists team state"| node_teamstore
node_server -->|"hosts MCP"| node_mcpserver
node_mcpserver -->|"registers tools"| node_mcpcatalog
node_mcpclient -->|"calls tools"| node_mcpserver

click node_cli "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/cli/server.ts"
click node_config "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/config/config.ts"
click node_registry "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/registry/registry.ts"
click node_server "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/server.ts"
click node_admin "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/admin/client.ts"
click node_dispatchers "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/index.ts"
click node_commands "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/command/port.ts"
click node_dispatcher "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/dispatcher-service/index.ts"
click node_runtimecatalog "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/agent-runtime/catalog.ts"
click node_codex "https://github.com/excitedjs/dreamux/blob/next/packages/agent-runtime/codex/src/runtime.ts"
click node_claude "https://github.com/excitedjs/dreamux/blob/next/packages/agent-runtime/claude-code/src/runtime.ts"
click node_channelcatalog "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/channel/catalog.ts"
click node_feishu "https://github.com/excitedjs/dreamux/blob/next/packages/channel/feishu-channel/src/feishu-channel.ts"
click node_transport "https://github.com/excitedjs/dreamux/blob/next/packages/channel/feishu-transport/src/transport/feishu.ts"
click node_mcpserver "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/mcp/server.ts"
click node_mcpcatalog "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/mcp/catalog.ts"
click node_teams "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/team-service/index.ts"
click node_teammates "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/teammate-service/index.ts"
click node_teamstore "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/team-collection/store.ts"
click node_scheduler "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/scheduler/service.ts"
click node_workflows "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/workflow-service/index.ts"
click node_worktrees "https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/worktree/manager.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_cli,node_config,node_registry,node_server,node_admin,node_channeluser,node_mcpclient toneBlue
class node_dispatchers,node_commands,node_dispatcher,node_runtimecatalog,node_codex,node_claude toneAmber
class node_channelcatalog,node_feishu,node_transport toneMint
class node_mcpserver,node_mcpcatalog toneRose
class node_teams,node_teammates,node_teamstore,node_scheduler,node_workflows,node_worktrees,node_operator,node_admincaller toneIndigo
```

## Components

### Host lifecycle

- [Serve CLI](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/cli/server.ts): `packages/dreamux/src/cli/server.ts`
- [Config loader](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/config/config.ts): `packages/dreamux/src/config/config.ts`
- [Provider registry](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/registry/registry.ts): `packages/dreamux/src/registry/registry.ts`
- [Dreamux server](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/server.ts): `packages/dreamux/src/server.ts`
- [Admin socket](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/admin/client.ts): `packages/dreamux/src/admin/client.ts`

### Dispatcher runtime

- [Dispatcher collection](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/index.ts): `packages/dreamux/src/service/index.ts`
- [Command port](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/command/port.ts): `packages/dreamux/src/command/port.ts`
- [Dispatcher services](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/dispatcher-service/index.ts): `packages/dreamux/src/service/dispatcher-service/index.ts`
- [Runtime catalog](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/agent-runtime/catalog.ts): `packages/dreamux/src/agent-runtime/catalog.ts`
- [Codex runtime](https://github.com/excitedjs/dreamux/blob/next/packages/agent-runtime/codex/src/runtime.ts): `packages/agent-runtime/codex/src/runtime.ts`
- [Claude runtime](https://github.com/excitedjs/dreamux/blob/next/packages/agent-runtime/claude-code/src/runtime.ts): `packages/agent-runtime/claude-code/src/runtime.ts`

### Channel integrations

- [Channel catalog](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/channel/catalog.ts): `packages/dreamux/src/channel/catalog.ts`
- [Feishu channel](https://github.com/excitedjs/dreamux/blob/next/packages/channel/feishu-channel/src/feishu-channel.ts): `packages/channel/feishu-channel/src/feishu-channel.ts`
- [Feishu transport](https://github.com/excitedjs/dreamux/blob/next/packages/channel/feishu-transport/src/transport/feishu.ts): `packages/channel/feishu-transport/src/transport/feishu.ts`

### MCP surfaces

- [MCP server](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/mcp/server.ts): `packages/dreamux/src/mcp/server.ts`
- [MCP catalog](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/mcp/catalog.ts): `packages/dreamux/src/mcp/catalog.ts`

### State and automation

- [Team services](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/team-service/index.ts): `packages/dreamux/src/service/team-service/index.ts`
- [Teammate services](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/teammate-service/index.ts): `packages/dreamux/src/service/teammate-service/index.ts`
- [Team store](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/team-collection/store.ts): `packages/dreamux/src/service/team-collection/store.ts`
- [Scheduler](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/scheduler/service.ts): `packages/dreamux/src/service/scheduler/service.ts`
- [Workflow service](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/workflow-service/index.ts): `packages/dreamux/src/service/workflow-service/index.ts`
- [Worktree manager](https://github.com/excitedjs/dreamux/blob/next/packages/dreamux/src/service/worktree/manager.ts): `packages/dreamux/src/service/worktree/manager.ts`

### Other components

- **Operator**
- **Admin caller**
- **Channel user**
- **MCP client**

## Connections

- Operator → Serve CLI: starts
- Serve CLI → Provider registry: seeds providers
- Serve CLI → Config loader: loads config
- Config loader → Provider registry: loads implementations
- Serve CLI → Dreamux server: starts
- Dreamux server → Dispatcher collection: boots
- Dreamux server → Command port: composes
- Dreamux server → Admin socket: owns IPC
- Admin caller → Admin socket: sends commands
- Dispatcher collection → Dispatcher services: runs
- Dispatcher collection → Runtime catalog: resolves providers
- Dispatcher collection → Channel catalog: resolves providers
- Runtime catalog → Codex runtime: selects
- Runtime catalog → Claude runtime: selects
- Channel catalog → Feishu channel: selects
- Channel user → Feishu transport: sends message
- Feishu channel → Feishu transport: uses I/O
- Feishu channel → Command port: invokes
- Command port → Dispatcher services: dispatches
- Dispatcher services → Team services: manages teams
- Dispatcher services → Teammate services: manages teammates
- Dispatcher services → Scheduler: schedules work
- Dispatcher services → Workflow service: runs workflows
- Teammate services → Worktree manager: manages workspaces
- Team services → Team store: persists team state
- Dreamux server → MCP server: hosts MCP
- MCP server → MCP catalog: registers tools
- MCP client → MCP server: calls tools