# deepcoldy/botmux architecture

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

- Interactive diagram: https://gitdiagram.com/deepcoldy/botmux
- Repository: https://github.com/deepcoldy/botmux

## Overview

botmux bridges Feishu/Lark conversations to existing AI coding CLIs and agents. Its principal flow is a user message entering the daemon, becoming an isolated session running through a CLI adapter and backend, then returning as a streaming Feishu card; users can also operate sessions through a web terminal. The map includes documented scheduling, webhook, multi-bot, workflow, plugin, and dashboard capabilities. Relationships beyond the sampled excerpts are based on README statements; unsampled implementation details are not inferred.

Main entry points: [`src/core/session-manager.ts`](https://github.com/deepcoldy/botmux/blob/master/src/core/session-manager.ts) (Session manager), [`src/adapters/cli/runtime.ts`](https://github.com/deepcoldy/botmux/blob/master/src/adapters/cli/runtime.ts) (CLI runtime), [`src/adapters/backend/types.ts`](https://github.com/deepcoldy/botmux/blob/master/src/adapters/backend/types.ts) (Session backends), [`src/dashboard/http.ts`](https://github.com/deepcoldy/botmux/blob/master/src/dashboard/http.ts) (Dashboard API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Messaging and entry"]
  node_daemon["Daemon<br/>[daemon.ts]"]
  node_lark["Lark transport<br/>[client.ts]"]
  node_cards["Card handling<br/>[card-handler.ts]"]
end

subgraph group_sessions["Sessions and agents"]
  node_registry["Bot registry<br/>[bot-registry.ts]"]
  node_session["Session manager<br/>[session-manager.ts]"]
  node_adapter["CLI adapters<br/>[registry.ts]"]
  node_cli_runtime["CLI runtime<br/>[runtime.ts]"]
  node_backend["Session backends<br/>[types.ts]"]
  node_mojo["Mojo backend<br/>[mojo-types.ts]"]
  node_riff["Riff backend<br/>[riff-backend.ts]"]
  node_read_isolation["Read isolation<br/>[read-isolation.ts]"]
  node_session_store[("Session state<br/>[session-manager.ts]")]
end

subgraph group_operations["Control and automation"]
  node_scheduler["Scheduler<br/>[scheduler.ts]"]
  node_webhooks["Webhook triggers<br/>[webhook-routes.ts]"]
end

subgraph group_interfaces["User interfaces"]
  node_terminal["Web terminal<br/>[terminal-proxy.ts]"]
  node_dashboard["Dashboard API<br/>[http.ts]"]
  node_web_ui["Dashboard UI<br/>[app.tsx]"]
  node_workbench["Agent workbench"]
end

subgraph group_extensions["Workflows and extensions"]
  node_workflows["V3 workflows"]
  node_plugins["Plugin services<br/>[service-manager.ts]"]
  node_skills["Skill prompts"]
end

node_user(("Feishu user"))
node_cli_user(("Coding CLI / agent"))
node_browser(("Browser user"))
node_external_system(("External trigger"))

node_user -->|"sends message"| node_lark
node_lark -->|"delivers events"| node_daemon
node_daemon -->|"starts sessions"| node_session
node_session -->|"resolves bot"| node_registry
node_session -->|"selects adapter"| node_adapter
node_adapter -->|"configures CLI"| node_cli_runtime
node_cli_runtime -.->|"uses backend"| node_backend
node_backend -.->|"supports"| node_mojo
node_backend -.->|"supports"| node_riff
node_session -->|"applies isolation"| node_read_isolation
node_session -.->|"manages state"| node_session_store
node_cli_runtime -->|"runs agent"| node_cli_user
node_session -->|"streams output"| node_cards
node_cards -->|"updates cards"| node_lark
node_browser -->|"operates session"| node_terminal
node_terminal -->|"controls session"| node_session
node_browser -->|"uses dashboard"| node_web_ui
node_web_ui -.->|"calls API"| node_dashboard
node_dashboard -.->|"manages sessions"| node_session
node_browser -->|"uses workbench"| node_workbench
node_scheduler -->|"starts scheduled turns"| node_session
node_external_system -->|"triggers tasks"| node_webhooks
node_webhooks -->|"dispatches trigger"| node_session
node_user -->|"starts orchestration"| node_workflows
node_workflows -->|"reports progress"| node_cards
node_dashboard -.->|"configures services"| node_plugins
node_session -.->|"uses prompt fragments"| node_skills

click node_daemon "https://github.com/deepcoldy/botmux/blob/master/src/daemon.ts"
click node_lark "https://github.com/deepcoldy/botmux/blob/master/src/im/lark/client.ts"
click node_cards "https://github.com/deepcoldy/botmux/blob/master/src/im/lark/card-handler.ts"
click node_registry "https://github.com/deepcoldy/botmux/blob/master/src/bot-registry.ts"
click node_session "https://github.com/deepcoldy/botmux/blob/master/src/core/session-manager.ts"
click node_adapter "https://github.com/deepcoldy/botmux/blob/master/src/adapters/cli/registry.ts"
click node_cli_runtime "https://github.com/deepcoldy/botmux/blob/master/src/adapters/cli/runtime.ts"
click node_backend "https://github.com/deepcoldy/botmux/blob/master/src/adapters/backend/types.ts"
click node_mojo "https://github.com/deepcoldy/botmux/blob/master/src/adapters/backend/mojo-types.ts"
click node_riff "https://github.com/deepcoldy/botmux/blob/master/src/adapters/backend/riff-backend.ts"
click node_read_isolation "https://github.com/deepcoldy/botmux/blob/master/src/adapters/cli/read-isolation.ts"
click node_session_store "https://github.com/deepcoldy/botmux/blob/master/src/core/session-manager.ts"
click node_terminal "https://github.com/deepcoldy/botmux/blob/master/src/core/terminal-proxy.ts"
click node_dashboard "https://github.com/deepcoldy/botmux/blob/master/src/dashboard/http.ts"
click node_web_ui "https://github.com/deepcoldy/botmux/blob/master/src/dashboard/web/app.tsx"
click node_workbench "https://github.com/deepcoldy/botmux/blob/master/src/dashboard/web/agent-workbench-page.tsx"
click node_scheduler "https://github.com/deepcoldy/botmux/blob/master/src/core/scheduler.ts"
click node_webhooks "https://github.com/deepcoldy/botmux/blob/master/src/dashboard/webhook-routes.ts"
click node_workflows "https://github.com/deepcoldy/botmux/blob/master/src/im/lark/v3-progress-card-manager.ts"
click node_plugins "https://github.com/deepcoldy/botmux/blob/master/src/core/plugins/service-manager.ts"
click node_skills "https://github.com/deepcoldy/botmux/blob/master/src/skills/prompt-fragments.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_daemon,node_lark,node_cards,node_user,node_browser toneBlue
class node_registry,node_session,node_adapter,node_cli_runtime,node_backend,node_mojo,node_riff,node_read_isolation,node_session_store toneAmber
class node_scheduler,node_webhooks toneMint
class node_terminal,node_dashboard,node_web_ui,node_workbench toneRose
class node_workflows,node_plugins,node_skills,node_cli_user,node_external_system toneIndigo
```

## Components

### Messaging and entry

- [Daemon](https://github.com/deepcoldy/botmux/blob/master/src/daemon.ts): `src/daemon.ts`
- [Lark transport](https://github.com/deepcoldy/botmux/blob/master/src/im/lark/client.ts): `src/im/lark/client.ts`
- [Card handling](https://github.com/deepcoldy/botmux/blob/master/src/im/lark/card-handler.ts): `src/im/lark/card-handler.ts`

### Sessions and agents

- [Bot registry](https://github.com/deepcoldy/botmux/blob/master/src/bot-registry.ts): `src/bot-registry.ts`
- [Session manager](https://github.com/deepcoldy/botmux/blob/master/src/core/session-manager.ts): `src/core/session-manager.ts`
- [CLI adapters](https://github.com/deepcoldy/botmux/blob/master/src/adapters/cli/registry.ts): `src/adapters/cli/registry.ts`
- [CLI runtime](https://github.com/deepcoldy/botmux/blob/master/src/adapters/cli/runtime.ts): `src/adapters/cli/runtime.ts`
- [Session backends](https://github.com/deepcoldy/botmux/blob/master/src/adapters/backend/types.ts): `src/adapters/backend/types.ts`
- [Mojo backend](https://github.com/deepcoldy/botmux/blob/master/src/adapters/backend/mojo-types.ts): `src/adapters/backend/mojo-types.ts`
- [Riff backend](https://github.com/deepcoldy/botmux/blob/master/src/adapters/backend/riff-backend.ts): `src/adapters/backend/riff-backend.ts`
- [Read isolation](https://github.com/deepcoldy/botmux/blob/master/src/adapters/cli/read-isolation.ts): `src/adapters/cli/read-isolation.ts`
- [Session state](https://github.com/deepcoldy/botmux/blob/master/src/core/session-manager.ts): `src/core/session-manager.ts`

### Control and automation

- [Scheduler](https://github.com/deepcoldy/botmux/blob/master/src/core/scheduler.ts): `src/core/scheduler.ts`
- [Webhook triggers](https://github.com/deepcoldy/botmux/blob/master/src/dashboard/webhook-routes.ts): `src/dashboard/webhook-routes.ts`

### User interfaces

- [Web terminal](https://github.com/deepcoldy/botmux/blob/master/src/core/terminal-proxy.ts): `src/core/terminal-proxy.ts`
- [Dashboard API](https://github.com/deepcoldy/botmux/blob/master/src/dashboard/http.ts): `src/dashboard/http.ts`
- [Dashboard UI](https://github.com/deepcoldy/botmux/blob/master/src/dashboard/web/app.tsx): `src/dashboard/web/app.tsx`
- [Agent workbench](https://github.com/deepcoldy/botmux/blob/master/src/dashboard/web/agent-workbench-page.tsx): `src/dashboard/web/agent-workbench-page.tsx`

### Workflows and extensions

- [V3 workflows](https://github.com/deepcoldy/botmux/blob/master/src/im/lark/v3-progress-card-manager.ts): `src/im/lark/v3-progress-card-manager.ts`
- [Plugin services](https://github.com/deepcoldy/botmux/blob/master/src/core/plugins/service-manager.ts): `src/core/plugins/service-manager.ts`
- [Skill prompts](https://github.com/deepcoldy/botmux/blob/master/src/skills/prompt-fragments.ts): `src/skills/prompt-fragments.ts`

### Other components

- **Feishu user**
- **Coding CLI / agent**
- **Browser user**
- **External trigger**

## Connections

- Feishu user → Lark transport: sends message (evidence: `README.md`)
- Lark transport → Daemon: delivers events (evidence: `README.md`)
- Daemon → Session manager: starts sessions (evidence: `README.md`)
- Session manager → Bot registry: resolves bot (evidence: `src/core/session-manager.ts`)
- Session manager → CLI adapters: selects adapter (evidence: `src/core/session-manager.ts`)
- CLI adapters → CLI runtime: configures CLI (evidence: `src/adapters/cli/registry.ts`)
- CLI runtime → Session backends: uses backend
- Session backends → Mojo backend: supports
- Session backends → Riff backend: supports
- Session manager → Read isolation: applies isolation (evidence: `src/core/session-manager.ts`)
- Session manager → Session state: manages state (evidence: `src/core/session-manager.ts`)
- CLI runtime → Coding CLI / agent: runs agent (evidence: `README.md`)
- Session manager → Card handling: streams output (evidence: `README.md`)
- Card handling → Lark transport: updates cards (evidence: `README.md`)
- Browser user → Web terminal: operates session (evidence: `README.md`)
- Web terminal → Session manager: controls session (evidence: `README.md`)
- Browser user → Dashboard UI: uses dashboard (evidence: `README.md`)
- Dashboard UI → Dashboard API: calls API
- Dashboard API → Session manager: manages sessions
- Browser user → Agent workbench: uses workbench (evidence: `README.md`)
- Scheduler → Session manager: starts scheduled turns (evidence: `README.md`)
- External trigger → Webhook triggers: triggers tasks (evidence: `README.md`)
- Webhook triggers → Session manager: dispatches trigger (evidence: `src/dashboard/webhook-routes.ts`)
- Feishu user → V3 workflows: starts orchestration (evidence: `README.md`)
- V3 workflows → Card handling: reports progress (evidence: `src/im/lark/v3-progress-card-manager.ts`)
- Dashboard API → Plugin services: configures services
- Session manager → Skill prompts: uses prompt fragments
