How netease-youdao/lobsterai works
1. Overall shape
LobsterAI is a cross-platform Electron desktop app with a strict three-process split: main process for privileged work, preload as the narrow bridge, and React renderer for all UI/state. The core architecture is “local assistant orchestration” rather than a thin client/server app.
2. Main process as the control plane
src/main/main.ts owns window lifecycle, IPC registration, persistence, agent execution, IM bridges, tray, and update/install concerns. This is the trusted boundary: filesystem, command execution, network access, and background integrations all terminate here.
3. Renderer as the presentation + interaction layer
src/renderer/ is a React 18 + Redux Toolkit application. It contains the user-facing surfaces for Cowork sessions, agents, skills, scheduled tasks, IM settings, MCP, and updates. Renderer code talks to the backend only through IPC-backed service modules, not directly to Node APIs.
4. Preload as the security membrane
src/main/preload.ts exposes a constrained window.electron API via contextBridge. That keeps context isolation intact, with node integration disabled and sandboxing enabled. The preload is the only sanctioned bridge between UI and privileged operations.
5. Cowork engine: the central workflow subsystem
The Cowork subsystem is the app’s core agent loop. src/main/libs/coworkRunner.ts and related helpers manage session execution, model routing, tool invocation, streamed updates, permission requests, and completion events. The renderer’s cowork views display this streamed state, while the main process keeps authoritative session/message history in storage.
6. Local persistence and session state
Storage is local-first and centered on SQLite (src/main/sqliteStore.ts, coworkStore.ts, mcpStore.ts, skillManager.ts, src/scheduledTask/metaStore.ts). The README’s kv, cowork_config, cowork_sessions, cowork_messages, and scheduled_tasks tables indicate the app persists configuration, conversation history, task definitions, and runtime metadata on-device.
7. Skills as packaged capability modules
The SKILLs/ directory is a major architectural boundary: each skill is a self-contained capability bundle with its own SKILL.md, scripts, and sometimes assets/libraries. Built-in skills cover document generation, web search, Playwright automation, Remotion video, PDF handling, email, canvas design, and custom skill creation. The main app loads/manages these skills through skillManager.ts, skillServices.ts, and renderer skill UIs.
8. Tooling/runtime expansion via OpenClaw and Claude
The agent execution layer can run with the Claude Agent SDK directly or through an OpenClaw runtime adapter (src/main/libs/agentEngine/*, openclawRuntimeAdapter.ts, claudeRuntimeAdapter.ts). Packaging scripts build and bundle a pinned OpenClaw runtime into the app, so the agent environment is shipped as part of the desktop product rather than fetched at runtime.
9. Scheduled tasks as a background orchestration path
Scheduled work is a separate subsystem spanning src/scheduledTask/ and src/main/ipcHandlers/scheduledTask/. It models cron-driven jobs, task policies, and run history, then launches Cowork sessions when triggers fire. This creates a second entry path into the agent engine besides direct user interaction.
10. IM integrations as remote control ingress/egress
src/main/im/ handles DingTalk, Feishu/Lark, Telegram, Discord, and NetEase IM/Bee connectivity. These gateways convert external chat events into internal cowork/task actions and send results back out. Architecturally, IM is an alternate front door into the same local agent and storage pipeline.
11. Memory, security, and policy enforcement
Memory extraction and injection live in src/main/libs/openclawMemory* and related cowork memory helpers; conversation turns are mined for preferences/facts and persisted for later context injection. Security is layered: explicit permission gating for tools, workspace restrictions, content sanitization in the renderer, and skill security scanning/auditing in src/main/libs/skillSecurity/.
12. Packaging and runtime dependencies
The repo includes substantial build infrastructure because the shipped app contains more than just Electron bundles. Packaging scripts assemble the app, OpenClaw runtime, and on Windows a portable Python runtime for skills. This means deployment is a composite artifact: desktop shell + embedded agent runtime + embedded capability runtimes.
13. External integration layer
The app uses external services only where they materially extend capabilities: IM APIs, web search providers, model providers, and browser automation. These integrations are mediated through specific modules and IPC boundaries, keeping the rest of the application local and deterministic.
14. Diagramming the main data flows
The key arrows to capture are: renderer UI → IPC services → main-process stores/engines → streamed events back to renderer; IM/scheduler triggers → cowork session creation → skills/tools/runtime execution → persisted session results; conversation output → memory extractor → persistent memory store → future context injection. That is the core architecture of the repository.
Main entry points: App.tsx App shell · main.ts Main entry · SKILLs Skill packs · coworkRunner.ts Cowork engine
Components 28
Main process
Privileged Electron control plane and local orchestration.
- Main entry · Bootstraps the app, window lifecycle, IPC, tray, and integrations.
src/main/main.ts - Preload bridge · Exposes the limited renderer API through contextBridge.
src/main/preload.ts - IPC + storage · Registers handlers and coordinates persistence for app state.
src/main/sqliteStore.ts - Cowork engine · Runs sessions, streams turns, routes tools, and finalizes results.
src/main/libs/coworkRunner.ts - Agent router · Selects Claude or OpenClaw execution paths for cowork runs.
src/main/libs/agentEngine/coworkEngineRouter.ts - Memory policy · Extracts, judges, stores, and reinjects long-term memory context.
src/main/libs/coworkMemoryExtractor.ts - Skill manager · Loads, validates, and exposes packaged skills to the engine and UI.
src/main/skillManager.ts - Skill security · Audits skill bundles and enforces safety rules for execution.
src/main/libs/skillSecurity/skillSecurityScanner.ts - IM gateways · Connects DingTalk, Feishu/Lark, Telegram, Discord, and NIM channels.
src/main/im/index.ts - Task ingress · Receives scheduled-task IPC and launches jobs into cowork sessions.
src/main/ipcHandlers/scheduledTask/index.ts
Renderer
React UI and IPC-backed client state.
- App shell · Top-level React application and navigation shell.
src/renderer/App.tsx - Cowork UI · Session list, detail, prompts, permissions, and streamed turn display.
src/renderer/components/cowork/CoworkView.tsx - Redux store · Client-side state for cowork, agents, IM, MCP, skills, tasks, and updates.
src/renderer/store/index.ts - IPC services · Typed client modules that call the main process via the preload API.
src/renderer/services/api.ts - Skills UI · Manages installed skills, security reports, and skill-specific settings.
src/renderer/components/skills/SkillsView.tsx - Tasks UI · Creates scheduled tasks, reviews runs, and opens task sessions.
src/renderer/components/scheduledTasks/ScheduledTasksView.tsx - IM settings · Configures external chat gateways and delivery behavior.
src/renderer/components/im/IMSettings.tsx - MCP UI · Manages MCP servers and local registry-backed connections.
src/renderer/components/mcp/McpView.tsx - Updates UI · Surfaces app update status and install actions.
src/renderer/components/update/AppUpdateModal.tsx
Scheduled tasks
Background task orchestration and policies.
- Task engine · Models cron jobs, policies, mapping, and run history.
src/scheduledTask/cronJobService.ts - Task policies · Resolves manual, cowork, IM, and legacy task execution policies.
src/scheduledTask/policies/registry.ts
Skills
Packaged capability modules shipped with the app.
- Skill packs · Repository of packaged skills and their supporting scripts/assets.
SKILLs - Web search · Dedicated web-search skill with embedded server and browser automation.
SKILLs/web-search - Doc tools · Document, presentation, and spreadsheet generation/validation skills.
SKILLs/docx - Media skills · Skills for video, image, canvas, PDF, and email/media workflows.
SKILLs/remotion
Runtime bundle
Embedded OpenClaw, Python, and packaging support.
- OpenClaw runtime · Pinned runtime and bootstrap artifacts packaged into the desktop app.
resources/openclaw-bootstrap/manifest.json - Python runtime · Bundled runtime used by selected skills and packaging workflows.
resources/node-runtime - Build scripts · Assembles the app, runtime bundles, patches, and installers.
scripts/build-openclaw-runtime.sh
Connections 32
- Main entry → Preload bridge: exposes bridge · Main process loads the preload script for isolated renderer access.
- Preload bridge → IPC services: enables IPC · Renderer services use the constrained window API provided by preload.
- App shell → Redux store: uses · UI reads and updates application state through Redux.
- App shell → Cowork UI: navigates · Primary surface for assistant sessions and turn streaming.
- App shell → Skills UI: opens · Users manage packaged skills from the app shell.
- App shell → Tasks UI: opens · Users manage scheduled tasks from the app shell.
- App shell → IM settings: opens · Users configure chat integrations from the UI.
- App shell → MCP UI: opens · Users manage MCP connections from the UI.
- App shell → Updates UI: shows · Update status and install flows are presented in the shell.
- IPC services → Main entry: calls · IPC-backed services invoke privileged main-process handlers.
- Main entry → IPC + storage: registers · Main process wires IPC and persists app/workspace state.
- Main entry → Cowork engine: orchestrates · Main process owns the authoritative cowork execution flow.
- Main entry → Skill manager: loads skills · Skills are discovered and managed in the trusted process.
- Skill manager → Skill security: validates · Skill bundles are scanned before being enabled.
- Main entry → IM gateways: connects · Chat gateway events enter the local assistant pipeline here.
- Main entry → Task ingress: handles · Scheduled-task IPC enters the app through this boundary.
- Task ingress → Task engine: starts jobs · Cron-triggered work is routed into the task engine.
- Task engine → Task policies: selects policy · Execution behavior depends on task policy type.
- Task engine → Cowork engine: launches · Scheduled tasks create cowork sessions for execution.
- IM gateways → Cowork engine: creates sessions · Incoming IM events can become cowork runs or replies.
- Cowork engine → Agent router: routes · Execution chooses Claude SDK or OpenClaw runtime path.
- Agent router → OpenClaw runtime: uses · OpenClaw runs against the embedded runtime bundle.
- Agent router → Python runtime: uses · Some skills and packaging flows depend on the bundled Python runtime.
- Cowork engine → Memory policy: extracts memory · Conversation turns are mined for reusable context.
- Memory policy → IPC + storage: persists · Memory and session metadata are stored locally.
- Skill manager → Skill packs: reads · Skill definitions and assets come from the SKILLs directory.
- Skill packs → Web search: contains · Representative packaged capability for web search and automation.
- Skill packs → Doc tools: contains · Representative packaged capability for document and presentation work.
- Skill packs → Media skills: contains · Representative packaged capability for media, PDF, and creative workflows.
- Build scripts → OpenClaw runtime: packages · Build scripts assemble and ship the embedded runtime artifacts.
- Build scripts → Python runtime: bundles · Windows/runtime setup includes the portable Python dependency.
- Build scripts → Skill packs: syncs · Packaging and runtime preparation include local skill assets.