## File: README.md

<h1 align="center">
  
  LobsterAI
</h1>









<h3 align="center">[Download LobsterAI](https://lobsterai.youdao.com/#/download-list)</h3>



LobsterAI is a desktop Agent that can operate in your real working environment: local files, terminal commands, browser workflows, documents, spreadsheets, slides, IM channels, scheduled jobs, and project workspaces.

Cowork is the LobsterAI product/session layer. OpenClaw is the runtime and gateway underneath it. That split lets LobsterAI keep local persistence, permissions, UI state, artifacts, agents, memory, and IM bindings in the desktop app while using OpenClaw for agent execution.

## Features

### Desktop Cowork Sessions

Run long-form Agent tasks against local projects and files. LobsterAI streams progress, keeps session history, renders tool output, and asks for approval before sensitive actions such as file operations, terminal commands, or network access.

### Multi-Agent Workflows

Create custom Agents with their own identity, model choice, skills, working directory, enabled state, and IM bindings. Keep the Main Agent for general work and use specialized Agents for repeatable roles.

### Expert Kits

Install scenario-oriented Expert Kits that package capability selections and references for common workflows. Kits are selected independently from direct skills, so a workflow can combine curated kits with individual tools.

### Skills

LobsterAI ships with 28 built-in skills configured in `SKILLs/skills.config.json`, including web search, Word documents, spreadsheets, PowerPoint, PDF processing, Remotion video generation, browser automation, image/video generation, stock research, content writing, email, weather, and skill creation.

### MCP Servers

Connect external tools and data sources through Model Context Protocol servers. LobsterAI stores user-configured servers locally and syncs enabled servers into OpenClaw.

### Scheduled Tasks

Create recurring work either by conversation or through the scheduled task UI. Use it for daily news digests, inbox summaries, website monitoring, weekly reports, and other repeatable work.

### IM Remote Control

Reach your desktop Agent from WeChat, WeCom, DingTalk, Feishu/Lark, QQ, Telegram, Discord, NetEase IM, NetEase Bee, POPO, and email. Multi-instance platforms can bind different accounts or channels to different Agents.

### Rich Artifacts

Preview and manage generated HTML, SVG, images, video, Mermaid diagrams, code, Markdown, text, documents, and local service artifacts inside the desktop app.

### Local Memory And Data

Sessions and app data live locally in SQLite. OpenClaw workspace memory uses files such as `MEMORY.md`, `USER.md`, `SOUL.md`, and daily notes, so durable preferences and project context can carry across sessions.

## Real-World Prompts

| Scenario | Example prompt |
| --- | --- |
| Build a local system | "I still track inventory and sales in Excel. Build a local inventory system that records purchases and sales, calculates stock and profit, and opens in my browser." |
| Analyze local data | "Use `product-growth.xlsx` to build a visual dashboard and summarize the main growth drivers." |
| Generate a deck | "Research the AI Agent market and turn the findings into a presentation." |
| Automate browser checks | "Open the ads dashboard every morning, check spend and conversion anomalies, and summarize likely causes." |
| Screen documents | "Turn the resumes in this folder into a screening sheet and shortlist the strongest candidates against the JD." |
| Run scheduled work | "Every weekday at 9 AM, collect yesterday's AI news and send me a concise digest." |

## How It Works



- **Renderer**: React, Redux Toolkit, Tailwind, artifact renderers, settings, agent/session UI, skills, MCP, scheduled tasks, and IM configuration.
- **Main process**: Electron lifecycle, IPC, SQLite persistence, auth, logging, OpenClaw startup, runtime repair, skill sync, IM gateways, and artifact services.
- **OpenClaw integration**: `openclawEngineManager`, `openclawConfigSync`, `openclawRuntimeAdapter`, and `coworkEngineRouter` translate LobsterAI state into OpenClaw runtime behavior.

## Install

### Desktop

Download the latest macOS and Windows installers from [Official Website](https://lobsterai.youdao.com/) or [GitHub Releases](https://github.com/netease-youdao/LobsterAI/releases).

### Run From Source

Requirements:

- Node.js `>=24.15.0 <25`
- npm

```bash
git clone https://github.com/netease-youdao/LobsterAI.git
cd LobsterAI
npm install
```

First development run:

```bash
npm run electron:dev:openclaw
```

Daily development after the pinned OpenClaw runtime exists:

```bash
npm run electron:dev
```

The renderer dev server runs at `http://localhost:5175`.

## Developing

```bash
# Production renderer bundle
npm run build

# Electron main/preload TypeScript build
npm run compile:electron

# Official Vitest entry used by CI
npm test

# Full ESLint across src; may expose existing legacy debt
npm run lint

# CI-style lint for touched TypeScript files
npx eslint --ext ts,tsx --report-unused-disable-directives --max-warnings 0 <files>
```

### OpenClaw Runtime

The pinned OpenClaw version and third-party plugin list live in `package.json` under `openclaw`.

```bash
# Build the current-platform runtime manually
npm run openclaw:runtime:host

# Use a custom OpenClaw source checkout
OPENCLAW_SRC=/path/to/openclaw npm run electron:dev:openclaw

# Force runtime rebuild
OPENCLAW_FORCE_BUILD=1 npm run electron:dev:openclaw

# Keep a local OpenClaw checkout on its current branch/tag
OPENCLAW_SKIP_ENSURE=1 npm run electron:dev:openclaw
```

## Packaging


Build desktop installers

```bash
# macOS
npm run dist:mac
npm run dist:mac:x64
npm run dist:mac:arm64
npm run dist:mac:universal

# Windows
npm run dist:win

# Linux
npm run dist:linux
```

Packaging bundles the OpenClaw runtime under `Resources/cfmind`. Windows builds also bundle a portable Python runtime under `resources/python-win`, so end users do not need to install Python manually.

Offline or private-source packaging can use:

- `LOBSTERAI_PORTABLE_PYTHON_ARCHIVE`
- `LOBSTERAI_PORTABLE_PYTHON_URL`
- `LOBSTERAI_WINDOWS_EMBED_PYTHON_VERSION`
- `LOBSTERAI_WINDOWS_EMBED_PYTHON_URL`
- `LOBSTERAI_WINDOWS_GET_PIP_URL`



## Project Map

| Path | Purpose |
| --- | --- |
| `src/main/main.ts` | Electron lifecycle, IPC registration, auth, logging, runtime startup, and service wiring |
| `src/main/libs/openclawEngineManager.ts` | OpenClaw gateway process, runtime state, ports, logs, restart, and repair |
| `src/main/libs/openclawConfigSync.ts` | Renders LobsterAI providers, models, agents, IM bindings, skills, MCP, and workspace instructions into OpenClaw config |
| `src/main/libs/agentEngine/openclawRuntimeAdapter.ts` | Translates OpenClaw gateway events into Cowork stream events |
| `src/main/coworkStore.ts` | Cowork sessions, messages, config, agents, memory metadata, and SQLite CRUD |
| `src/renderer/components/cowork/` | Main Cowork UI, prompt input, session detail, permissions, thinking/tool display, media, and voice input |
| `src/renderer/components/agent/` | Agent creation and settings UI |
| `src/renderer/components/skills/` | Skill management UI |
| `src/renderer/components/mcp/` | MCP server management UI |
| `src/renderer/components/scheduledTasks/` | Scheduled task list, form, detail, run history, and templates |
| `src/renderer/services/i18n.ts` | Renderer i18n dictionary and `t()` helper |
| `SKILLs/` | Bundled LobsterAI skills |

## Security And Data

- Renderer windows use context isolation, disabled Node integration, and sandboxing.
- Renderer-to-main access goes through preload IPC APIs.
- Sensitive tool actions are permission-gated and logged.
- App data is stored locally in `lobsterai.sqlite` under Electron `userData`.
- OpenClaw state, workspace memory, generated config, and gateway logs live under `userData/openclaw`.

## Community & Support

Join the WeChat group for help, feedback, and release updates:



Please use the repository issue templates for bugs and feature requests. For pull requests, include a short summary, linked issue when relevant, screenshots for UI changes, and notes for Electron-specific behavior such as IPC, storage, runtime, or windowing changes.

## Star History

[](https://www.star-history.com/?repos=netease-youdao%2Flobsterai&type=date&legend=bottom-right)

## License

[MIT License](LICENSE)

Built and maintained by [NetEase Youdao](https://www.youdao.com/).

---

## File: SKILLs/imap-smtp-email/README.md

# IMAP/SMTP Email Skill

Read and send email via IMAP/SMTP protocol. Works with any IMAP/SMTP server including Gmail, Outlook, 163.com, vip.163.com, 126.com, vip.126.com, 188.com, and vip.188.com.

## Quick Setup

1. **Configure accounts in LobsterAI Settings > Email.**

LobsterAI writes `accounts.json` for multi-account setups. Existing `.env` files are still read as a legacy single-account fallback.

Optional legacy `.env` format:

```bash
# IMAP Configuration (receiving email)
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=your@gmail.com
IMAP_PASS=your_app_password
IMAP_TLS=true
IMAP_MAILBOX=INBOX

# SMTP Configuration (sending email)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your@gmail.com
SMTP_PASS=your_app_password
SMTP_FROM=your@gmail.com
```

2. **Install dependencies:**
```bash
npm install
```

3. **Test the connection:**
```bash
node scripts/imap.js check
node scripts/smtp.js test
```

## Account Selection

```bash
# Use the default enabled account
node scripts/imap.js check

# List account IDs without secrets
node scripts/imap.js accounts
node scripts/smtp.js accounts

# Use a specific account
node scripts/imap.js check --account work

# Fan out to every enabled account for read/list commands
node scripts/imap.js check --all-accounts
node scripts/imap.js search --all-accounts --unseen
node scripts/imap.js list-mailboxes --all-accounts
```

## IMAP Commands (Receiving Email)

### Check for new emails
```bash
node scripts/imap.js check --limit 10
node scripts/imap.js check --account work --limit 10
node scripts/imap.js check --all-accounts --limit 10
node scripts/imap.js check --recent 2h        # Last 2 hours
node scripts/imap.js check --recent 30m       # Last 30 minutes
```

### Fetch specific email
```bash
node scripts/imap.js fetch 
node scripts/imap.js fetch  --account work
```

### Search emails
```bash
node scripts/imap.js search --unseen
node scripts/imap.js search --all-accounts --unseen
node scripts/imap.js search --from "sender@example.com"
node scripts/imap.js search --subject "important"
node scripts/imap.js search --recent 24h
```

### Mark as read/unread
```bash
node scripts/imap.js mark-read 
node scripts/imap.js mark-unread  --account work
```

### List mailboxes
```bash
node scripts/imap.js list-mailboxes
node scripts/imap.js list-mailboxes --all-accounts
```

## SMTP Commands (Sending Email)

### Test SMTP connection
```bash
node scripts/smtp.js test
node scripts/smtp.js test --account work
```

### Send email
```bash
# Simple text email
node scripts/smtp.js send --to recipient@example.com --subject "Hello" --body "World" --confirmed

# HTML email
node scripts/smtp.js send --to recipient@example.com --subject "Newsletter" --html --body "<h1>Welcome</h1>" --confirmed

# Email with attachment
node scripts/smtp.js send --to recipient@example.com --subject "Report" --body "Please find attached" --attach report.pdf --confirmed

# Multiple recipients
node scripts/smtp.js send --account work --to "a@example.com,b@example.com" --cc "c@example.com" --subject "Update" --body "Team update" --confirmed
```

Sending is blocked unless `--confirmed` is passed after the user confirms recipient, subject, sender account, and body.

## Common Email Servers

| Provider | IMAP Host | IMAP Port | SMTP Host | SMTP Port |
|----------|-----------|-----------|-----------|-----------|
| 163.com | imap.163.com | 993 | smtp.163.com | 465 |
| vip.163.com | imap.vip.163.com | 993 | smtp.vip.163.com | 465 |
| 126.com | imap.126.com | 993 | smtp.126.com | 465 |
| vip.126.com | imap.vip.126.com | 993 | smtp.vip.126.com | 465 |
| 188.com | imap.188.com | 993 | smtp.188.com | 465 |
| vip.188.com | imap.vip.188.com | 993 | smtp.vip.188.com | 465 |
| yeah.net | imap.yeah.net | 993 | smtp.yeah.net | 465 |
| Gmail | imap.gmail.com | 993 | smtp.gmail.com | 587 |
| Outlook | outlook.office365.com | 993 | smtp.office365.com | 587 |
| QQ Mail | imap.qq.com | 993 | smtp.qq.com | 587 |

**Important for 163.com:**
- Use **authorization code** (授权码), not account password
- Enable IMAP/SMTP in web settings first

## Configuration Options

**IMAP:**
- `IMAP_HOST` - Server hostname
- `IMAP_PORT` - Server port
- `IMAP_USER` - Your email address
- `IMAP_PASS` - Your password or app-specific password
- `IMAP_TLS` - Use TLS (true for SSL, false for STARTTLS)
- `IMAP_REJECT_UNAUTHORIZED` - Accept self-signed certs
- `IMAP_MAILBOX` - Default mailbox (INBOX)

**SMTP:**
- `SMTP_HOST` - Server hostname
- `SMTP_PORT` - Server port (587 for STARTTLS, 465 for SSL)
- `SMTP_SECURE` - true for SSL (465), false for STARTTLS (587)
- `SMTP_USER` - Your email address
- `SMTP_PASS` - Your password or app-specific password
- `SMTP_FROM` - Default sender email (optional)
- `SMTP_REJECT_UNAUTHORIZED` - Accept self-signed certs
- `EMAIL_REQUIRE_SEND_CONFIRMATION` - Set to `false` only for trusted automation that may send without `--confirmed`

## Troubleshooting

**Connection errors:**
- Verify IMAP/SMTP server is running and accessible
- Check host/port settings in `.env`

**Authentication failed:**
- For Gmail: Use App Password (not account password if 2FA enabled)
- For 163.com: Use authorization code (授权码), not account password

**TLS/SSL errors:**
- For self-signed certs: Set `IMAP_REJECT_UNAUTHORIZED=false` or `SMTP_REJECT_UNAUTHORIZED=false`

## Files

- `SKILL.md` - Skill documentation
- `accounts.json` - Multi-account credentials managed by LobsterAI Settings
- `scripts/imap.js` - IMAP CLI tool
- `scripts/smtp.js` - SMTP CLI tool
- `package.json` - Node.js dependencies
- `.env` - Legacy single-account credentials fallback

---

## File: SKILLs/web-search/README.md

# Web Search Skill

Real-time web search capability for LobsterAI using Playwright-controlled browser automation.

## Overview

The Web Search Skill enables LobsterAI to perform live web searches using Google and Bing, with automatic fallback when one provider is unavailable. The skill uses Playwright to control a local Chrome browser instance, making all operations transparent and observable.

## Features

- ✅ **Real-time Search** - Access current web information via Google with Bing fallback
- ✅ **Transparent Operations** - Visible browser window shows all actions
- ✅ **Playwright-Powered** - Robust browser automation using playwright-core
- ✅ **Simple CLI** - Easy-to-use command-line interface for Claude
- ✅ **HTTP API** - RESTful Bridge Server for advanced integrations
- ✅ **Auto-Managed** - Electron automatically starts/stops the service
- ✅ **Connection Caching** - Reuses browser connections for performance
- ✅ **Localhost Only** - Secure by design, no external exposure

## Architecture

```
Claude → Bash Tool → CLI Scripts → Bridge Server (localhost:8923) → Playwright → CDP → Chrome
```

**Components:**

1. **Bridge Server** - Express HTTP API for browser control
2. **Playwright Manager** - Connection and session management
3. **Browser Launcher** - Chrome lifecycle management
4. **Search Engines** - Google primary and Bing fallback
5. **CLI Scripts** - Simplified command-line interface
6. **Electron Integration** - Automatic service management

## Quick Start

### 1. Install Dependencies

```bash
cd SKILLs/web-search
npm install
```

### 2. Build

```bash
npm run build
```

### 3. Start Server

```bash
bash scripts/start-server.sh
```

### 4. Perform Search

```bash
bash scripts/search.sh "TypeScript tutorial" 5
```

### 5. Stop Server

```bash
bash scripts/stop-server.sh
```

## Usage

### Simple Search

```bash
bash SKILLs/web-search/scripts/search.sh "search query" [max_results]
```

**Examples:**

```bash
# Search for React 19 features (default 10 results)
bash scripts/search.sh "React 19 new features"

# Search for TypeScript tutorials (limit to 5 results)
bash scripts/search.sh "TypeScript tutorial" 5

# Search for current news
bash scripts/search.sh "AI news 2026" 10
```

### API Usage

See [examples/basic-search.md](examples/basic-search.md) for complete API documentation.

**Health Check:**
```bash
curl http://127.0.0.1:8923/api/health
```

**Search:**
```bash
curl -X POST http://127.0.0.1:8923/api/search \
  -H "Content-Type: application/json" \
  -d '{"connectionId": "...", "query": "...", "maxResults": 5}'
```

## Configuration

Default configuration in `server/config.ts`:

```typescript
{
  browser: {
    cdpPort: 9222,
    headless: false,  // Always visible
    chromeFlags: [/* ... */]
  },
  server: {
    port: 8923,
    host: '127.0.0.1'  // Localhost only
  },
  search: {
    defaultEngine: 'auto',
    fallbackOrder: ['google', 'bing'],
    defaultMaxResults: 10,
    searchTimeout: 30000,
    navigationTimeout: 15000
  }
}
```

## How Claude Uses This Skill

When Claude needs real-time information, it will:

1. **Recognize the need** - Questions about current events, latest docs, etc.
2. **Check server** - Verify Bridge Server is running
3. **Execute search** - Run `bash scripts/search.sh "query" N`
4. **Parse results** - Extract relevant information from Markdown output
5. **Answer user** - Provide response based on search results

**Example Interaction:**

```
User: What are the new features in Next.js 14?

Claude: [Calls: bash SKILLs/web-search/scripts/search.sh "Next.js 14 features" 5]

        Based on the latest search results, Next.js 14 introduces:
        1. Turbopack - 5000x faster than Webpack
        2. Server Actions (stable) - Simplified data mutations
        3. Partial Prerendering - Faster page loads
        ...
```

## API Endpoints

### Browser Management
- `POST /api/browser/launch` - Launch Chrome
- `POST /api/browser/connect` - Connect to browser
- `POST /api/browser/disconnect` - Disconnect
- `GET /api/browser/status` - Get status

### Search Operations
- `POST /api/search` - Execute search
- `POST /api/search/content` - Get URL content

### Page Operations
- `POST /api/page/navigate` - Navigate to URL
- `POST /api/page/screenshot` - Take screenshot
- `POST /api/page/content` - Get HTML content
- `POST /api/page/text` - Get text content

### Utility
- `GET /api/health` - Health check
- `GET /api/connections` - List connections

## Project Structure

```
SKILLs/web-search/
├── README.md                    # This file
├── SKILL.md                     # Skill documentation (for Claude)
├── LICENSE.txt                  # MIT License
├── package.json                 # Dependencies
├── tsconfig.json                # TypeScript config
├── server/                      # Bridge Server source
│   ├── index.ts                 # Express server
│   ├── config.ts                # Configuration
│   ├── playwright/
│   │   ├── manager.ts           # Playwright connection manager
│   │   ├── browser.ts           # Browser lifecycle
│   │   └── operations.ts        # Page operations
│   └── search/
│       ├── types.ts             # Type definitions
│       ├── google.ts            # Google search engine
│       └── bing.ts              # Bing fallback engine
├── scripts/                     # CLI tools
│   ├── start-server.sh          # Start Bridge Server
│   ├── stop-server.sh           # Stop Bridge Server
│   ├── search.sh                # Search CLI
│   ├── test-basic.js            # Basic functionality test
│   └── test-search.js           # Integration test
├── examples/                    # Usage examples
│   └── basic-search.md          # Complete usage guide
└── dist/                        # Compiled output (auto-generated)
```

## Testing

### Basic Functionality Test

```bash
node scripts/test-basic.js
```

Tests:
- Browser launch and connection
- Playwright connection management
- Page navigation
- Title and content extraction
- Screenshot capture
- Resource cleanup

### Search Integration Test

```bash
node scripts/test-search.js
```

Tests:
- Bridge Server startup
- Browser launch via API
- Playwright connection
- Bing search execution
- Result parsing
- Screenshot and text extraction
- Full cleanup

## Troubleshooting

### Server Won't Start

```bash
# Check logs
cat .server.log

# Check if port is in use
lsof -i :8923

# Rebuild
npm run build
```

### Chrome Not Found

Install Chrome:
- macOS: https://www.google.com/chrome/
- Linux: `sudo apt install chromium-browser`
- Windows: https://www.google.com/chrome/

### Connection Issues

```bash
# Clean up
bash scripts/stop-server.sh
rm .connection .server.pid

# Restart
bash scripts/start-server.sh
```

## Security

- **Localhost only** - Server binds to 127.0.0.1
- **No external access** - Not exposed to network
- **Isolated profile** - Separate Chrome user-data-dir
- **Visible operations** - All actions shown in browser window
- **No credentials** - No sensitive operations performed

## Performance

- **Server startup**: < 2 seconds
- **Browser launch**: < 3 seconds
- **Search latency**: < 1 second (network dependent)
- **Connection reuse**: Cached for multiple searches
- **Memory usage**: ~80MB (Bridge Server) + Chrome

## Requirements

- Node.js 18+
- Google Chrome or Chromium
- macOS, Windows, or Linux
- Internet connection for searches

## Dependencies

- `express` - HTTP server
- `playwright-core` - Browser automation
- `uuid` - Connection ID generation

## License

MIT License - See LICENSE.txt

## Future Enhancements

### Phase 2 (Optional)
- Advanced search options (date range, language, region)
- Result caching
- Deep content extraction

### Phase 3 (Optional)
- Native Cowork tool integration
- Form filling and multi-step automation
- CAPTCHA handling
- Network interception with Playwright

## Contributing

This skill is part of the LobsterAI project. For issues or suggestions:

1. Check existing issues
2. Create detailed bug reports
3. Include logs from `.server.log`
4. Test with latest version

## Credits

Built with:
- [Playwright](https://playwright.dev/) - Browser automation
- [Express](https://expressjs.com/) - HTTP server
- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) - Browser control

## Support

For help:
1. Read [examples/basic-search.md](examples/basic-search.md)
2. Check troubleshooting section
3. Review `.server.log` for errors
4. Test with `node scripts/test-basic.js`