Skip to content

Architecture

Mob is one TypeScript program, compiled with Bun into a single executable that embeds the web UI. The service owns a SQLite database and serves an authenticated loopback HTTP API; the desktop app (Electron, apps/desktop), the browser UI, the terminal UI and messaging channels are its clients. How each feature behaves is in features/.

The browser UI and the terminal UI share @mob/client. The core (packages/core) keeps Bun and Node APIs out of its service logic: SQLite and the host reach it through small interfaces. Its SQLite adapters use bun:sqlite on the host and SQLite WASM in the browser. apps/mob is the Bun host that gives it a database, files, processes and the command line.

Path Owns
packages/core/src/chat conversations and turns: ConversationService, the model loop, tool registry, hooks, command registry, approvals, context fitting (prune.ts, compact.ts), usage, search, and the SQLite store and schema
packages/core/src/llm the provider-neutral model interface and its drivers (openai, anthropic, demo, aisdk), and sending with retries (send.ts)
packages/core/src/provider providers.json, presets and the models.dev catalog
packages/core/src/app the HTTP routes and AI SDK UI stream (api.ts, http.ts, server.ts), plugin lifecycle (extension.ts), and plugin configuration (configuration.ts, plugin-config.ts)
packages/core/src/contracts.ts the wire contract shared by the service, host plugins and clients
packages/core/src/sqlite the SQLite adapters: bun:sqlite for the host, SQLite WASM for the browser
apps/mob/src/main.ts, config.ts, local.ts the CLI (commander), option definitions with their generated reference, XDG loading and live reload, process ownership, the database lock and the background lifecycle
apps/mob/src/plugins.ts the host’s plugins and shared channel bridge (channel.ts): agents (coding agents over ACP and Codex’s app server), email, telegram, cloudflare, wechat, mcp, skills, schedules.ts, sandbox (container runtimes and the model’s sandbox tool), runner and github
apps/mob/src/runner, apps/web/worker/relay.ts end-to-end encrypted remote control, with account ownership in apps/web/worker/runners.ts
apps/mob/scripts/build.ts, scripts/release.ts the single-executable build and the release archives
packages/client the wire contract (contracts.ts), typed client (api.ts), encrypted runner transport (remote.ts), authenticated HTTP, AI SDK message state, commands, approvals, polling and stream recovery, shared by Web and the terminal
packages/ui (@mob/ui) the design system: tokens and theme, the calf brand, source-owned shadcn/Radix controls, and the header styles and navigation links (src/site/header.css, src/site/navigation.ts) the site and docs share; no authentication or conversation state
packages/app (@mob/app) the React workspace (/app), with adapted AI Elements; browser authentication/storage, DOM input/completion and presentation adapt the shared client. mob embeds its build, the desktop app loads it and the site deploys it
apps/web (@mob/web) https://usemob.app: the landing page with GitHub sign-in and voxel scenes, the demo and account pages, the Cloudflare Worker (worker/) and the build that adds /app and /docs
apps/docs the Starlight documentation built from this repository’s Markdown
apps/tui the OpenTUI React terminal UI; terminal input, focus, layout and scrolling adapt the shared client
apps/desktop the Electron app around the mob executable
apps/dsh optional Bun process loading official DSH/Cordis tool plugins and exposing them to Mob over MCP
  • Every client and channel runs turns and decisions through ConversationService; Telegram, WeChat iLink and email call it in-process, other clients over HTTP. Store owns the service’s SQLite database; in the Bun host, files.ts uses separate .lock SQLite files for cross-process locking.
  • @mob/client shares conversation state across browser and terminal clients. In a browser, it uses document visibility events to pause polling while hidden and reload when shown. It uses the AI SDK’s headless Chat state container (exported by @ai-sdk/react), DefaultChatTransport and readUIMessageStream, not a new message protocol. UIs subscribe to its stable snapshot and translate their own input events. Commands still run in the service; navigation/form actions return to the UI. Authentication failures carry the rejected token through a callback; only Web dispatches a browser event.
  • Detaching a shared conversation client aborts its local readers, not the service’s turn. Explicit Stop requests the service to stop it. Grants, expiry and duplicate-effect protections remain service-owned; clients never automatically retry an approval decision or uncertain side effect.
  • Plugins register tools, commands, routes, configuration and background runs beside their own code; the engine does not name them (see Extensions). Code from outside Mob arrives only over MCP, including the optional DeepSeek Harness tools bridge, and as coding agents over ACP and Codex’s app server, which answer their tasks’ conversations through a Delegate.
  • SQLite is the only persistence dependency: no generic repository and no external queue. Schema changes are upgrades in packages/core/src/chat/schema.ts (see Releases and upgrades).
  • Model, Telegram, Cloudflare and S3 clients take per-instance transports, so their tests do not replace the global HTTP transport.