LobsterAI Documentation

LobsterAI implements a unified usage analytics reporting system to track application installation, core feature entry points, and key interactions. This data helps maintainers optimize features, improve compatibility, and prioritize development.

Key tracked data points include:

• Skills, MCPs, and Expert Kits used.
• Model sources and model types.
• Settings, Agents, and Scheduled Tasks.
• Session input box usage, message interactions, and artifact/browser previews.

Core Principles:

• Unified Entry Point: All logs are sent through a centralized service that handles log service addresses, common parameters, user identifiers, timestamps, and environment information.
• Non-Intrusive: Analytics reporting failures must not impact the application's original functionality.
• Privacy & Security: The system does not upload prompt text, conversation content, file contents, full file paths, full URLs, keys, API Keys, MCP environment variables/headers, IM credentials, or prompt hashes. It also avoids high-frequency tracking like mouse movements or streaming tokens to ensure performance.

LobsterAI is a desktop-level Agent designed for real-world work environments. Key features include:

• Desktop Cowork Sessions: Execute long-running tasks around local projects and files with real-time progress streaming and user approval for sensitive actions (file ops, terminal, network).
• Multi-Agent Workflows: Create custom Agents with independent identities, models, skills, and IM bindings.
• Expert Kits: Reusable workflows that bundle specific capabilities and reference information.
• Skills: 28 built-in skills (e.g., Web Search, Excel, PowerPoint, PDF, Browser Automation, Email, etc.) configured in SKILLs/skills.config.json.
• MCP Services: Integration with external tools and data via Model Context Protocol.
• Scheduled Tasks: Create periodic tasks (e.g., daily news summaries, website monitoring) via natural language or UI.
• IM Remote Control: Connect to the desktop Agent via WeChat, DingTalk, Feishu/Lark, Telegram, Discord, Email, and more.
• Artifacts: Preview and manage generated HTML, SVG, images, videos, Mermaid diagrams, and code.
• Local Memory: Uses local SQLite for session data and files like MEMORY.md, USER.md, and SOUL.md for cross-session context.

The LobsterAI scheduled task system is an end-to-end automation framework spanning three layers: Renderer (UI), Main Process (IPC/Business Logic), and the OpenClaw Gateway (Scheduling Engine).

Users can create scheduled tasks via the UI, IM chat, or Cowork sessions. The tasks are scheduled and executed by the OpenClaw Cron engine, and results are delivered back to users via IM channels or Webhooks.

Core Design Principles:

• OpenClaw Driven: All scheduling, execution, and delivery are handled natively by the OpenClaw Gateway. LobsterAI manages task CRUD and UI display but does not handle message delivery logic.
• Policy Pattern: Different task sources (UI, IM, Cowork, Legacy) use independent policy classes to control default parameters, binding relationships, and read-only fields.
• Origin Inference: The system uses the format of the sessionKey to reverse-infer the task source and execution binding, ensuring compatibility with legacy data.
• Streaming Polling: A 15-second polling mechanism is used to push real-time task status updates from OpenClaw to the UI.

The project is optimizing how local services are shared and deployed. Instead of wrapping all projects in a Node.js service (which consumes runtime resources and increases cold starts), projects that produce pure static files (like Vite, React, Vue, or Next.js static exports) will now use a dedicated Static Deployment path.

Key Improvements

• Resource Efficiency: Static sites use a dedicated share host instead of a Node runtime, preserving dynamic service quotas for actual backend services.
• Improved UX: Supports SPA history fallback (routing), root path resources, and static asset caching.
• Security: No user code is executed on the server for static deployments.

Deployment Logic Summary

Supported Scenarios

• Vite / React / Vue / Angular / Svelte: Detects build scripts and uploads the resulting static directory (e.g., dist/).
• Next.js Static Export: If out/index.html exists and no .next/standalone/server.js is present, it is treated as a static_site.
• SPA Routing: Supports history router fallback. If a requested path (e.g., /settings/profile) is not found in storage, the server returns index.html to let the frontend router handle it (when spaFallback = true).

LobsterAI supports two distinct access modes for HTML artifact sharing:

1. Code Mode (code): The default mode. Users receive a link and a specific share code. Accessing the link requires the user to input the correct share code.
2. Public Mode (public): The link is directly accessible to anyone without requiring a share code.

Key behaviors during mode switching:

• Switching code $\rightarrow$ public: The existing share code is preserved in the system but no longer required for access.
• Switching public $\rightarrow$ code: If a historical share code exists and is decryptable, it is reused. If no historical code exists, a new share code is generated.
• Content Updates: Switching the access mode without updating the artifact content does not trigger a contentUpdatedAt change or reset the moderationStatus. However, updating the content and switching the mode simultaneously will trigger content updates and moderation resets.

The macOS application update process (specifically installMacDmg() in src/main/libs/appUpdateInstaller.ts) has been redesigned to move from a non-atomic 'delete-then-copy' sequence to an atomic 'staged-copy-and-rename' sequence. This prevents the application from being deleted from the disk if the copy process fails (e.g., due to insufficient disk space or read errors).

Key Improvements:

• Staged Copy: The new version is copied to a hidden staging directory before the old version is touched.
• Atomic Swap: The old version is renamed to a backup, and the new version is renamed into its place using rename(2), which is atomic on the same filesystem.
• Automatic Rollback: If the swap fails, the system automatically restores the backup to the original location.
• Privilege Escalation Safety: The elevated (sudo) update path uses a single composite shell command to ensure the entire sequence (staging, backup, swap, and rollback) is executed atomically within a single password prompt session.

LobsterAI Cowork implements context compaction to manage long conversations. It provides users with visibility into context usage via a visual indicator (a ring) and allows for both automatic and manual context compaction to prevent context window overflow.

Key Features:

• Context Usage Monitoring: Displays a ring indicator showing the percentage of the context window used. Tooltips provide specific token counts.
• Automatic Compaction: Triggered by compactionCheckpointCount increments, inserting a system notification into the chat stream.
• Manual Compaction: Users can trigger compaction via the sessions.compact API. During manual compaction, the UI shows a loading state, and successful compaction refreshes the usage percentage and inserts a notification after the current message and media cards.
• Model Switching: Changing models automatically recalculates context usage based on the new model's context window.
• Compaction Metadata: Detailed information about compaction events (summary, tokens before/after, pre/post compaction metadata) is available via the OpenClaw gateway.