feishu-cursor-claw

Turn Feishu/Lark into a remote control for Cursor AI — text, voice, and images to code changes (and beyond).

Send a message on your phone, and your Mac writes code, reviews documents, or executes strategy tasks. No VPN, no SSH, no browser needed.

中文文档

---

Why

Cursor Agent CLI is incredibly powerful, but you need to be at your desk to use it. feishu-cursor bridges that gap: connect Feishu (Lark) to your local Cursor IDE via WebSocket, and control it from anywhere — your phone, a meeting, a coffee shop.

Beyond coding, executives and knowledge workers use this to co-create documents, review strategies, and manage files with AI — turning Cursor into a personal AI strategic partner driven entirely via instant messaging.

Architecture

Phone (Feishu) ──WebSocket──→ feishu-cursor ──Cursor CLI──→ Local Cursor IDE
                                    │                          │
                             ┌──────┼──────┐            --resume (session continuity)
                             │      │      │
                          Text   Image   Voice
                                          │
                               Volcengine STT (primary)
                               Local whisper (fallback)
                                    │
                             ┌──────┴──────┐
                          Scheduler    Heartbeat
                          (cron-jobs)  (.cursor/HEARTBEAT.md)

Features

• Multi-modal input: text, images, voice messages, files, rich text
• Session continuity: auto-resume conversations per workspace
• Voice-to-text: Volcengine Doubao STT (primary, high-accuracy Chinese) → local whisper-cpp (fallback)
• Live progress: real-time streaming of thinking / tool calls / responses via Feishu cards
• Elapsed time: completion cards show total execution time
• Session-level concurrency: same session serializes; different sessions run in parallel — no global limits, Cursor CLI manages its own lifecycle
• Project routing: prefix messages with project: to target different workspaces
• Hot reload: edit .env to change API keys, models, STT config — no restart needed
• Bilingual commands: all Feishu commands support both English and Chinese
• Security: sensitive commands (like API key changes) are blocked in group chats
• Smart error guidance: auth failures auto-display fix steps with dashboard links
• Model fallback: billing errors auto-downgrade to auto model with notification
• Memory system v2: OpenClaw-style identity + memory with embedding cache, incremental indexing, FTS5 BM25 keyword search, and vector hybrid search
• Autonomous memory: Cursor decides when to search memories via memory-tool.ts (no server-side injection — the AI is in control)
• Rules-based context: all identity, personality, and workspace rules are loaded via .cursor/rules/*.mdc — no extra tool calls needed at session start
• Scheduled tasks: AI-created cron jobs via cron-jobs.json — supports one-shot, interval, and cron expressions
• Heartbeat system: periodic AI check-in via .cursor/HEARTBEAT.md with active hours, background maintenance, AI auto-management of checklist, and state tracking via .cursor/memory/heartbeat-state.json
• Boot checklist: .cursor/BOOT.md runs once on every server start for self-checks and online notifications
• First-run ceremony: .cursor/BOOTSTRAP.md guides the AI through its "birth" — choosing a name, personality, and getting to know its owner
• Safety guardrails: anti-manipulation, anti-power-seeking, and human-oversight-first rules baked into workspace rules
• Memory recall protocol: mandatory memory search before answering questions about past work, decisions, or preferences
• Memory flush: proactive memory persistence during long conversations to prevent context window overflow data loss
• No mental notes: strict rule enforcing file-based persistence over ephemeral "I'll remember that"
• Auto workspace init: first run auto-copies identity/memory templates to your workspace

Quick Start

1. Prerequisites

• macOS with Bun installed
• Cursor IDE with Agent CLI (~/.local/bin/agent)
• A Feishu bot app (WebSocket mode, no public URL needed)

2. Install & Configure

git clone https://github.com/nongjun/feishu-cursor-claw.git
cd feishu-cursor-claw
bun install

cp .env.example .env
# Edit .env with your credentials

3. Run

bun run server.ts

You should see:

飞书长连接已启动，等待消息...

Send a message to your Feishu bot and watch Cursor work.

4. Auto-Start on Boot (Recommended)

bash service.sh install    # install + start via macOS launchd
bash service.sh status     # check if running
bash service.sh logs       # follow live logs

The service auto-restarts on crash and starts on boot — no manual intervention needed.

| Command | Description | |---------|-------------| | bash service.sh install | Install auto-start and launch now | | bash service.sh uninstall | Remove auto-start and stop | | bash service.sh start | Start the service | | bash service.sh stop | Stop the service | | bash service.sh restart | Restart the service | | bash service.sh status | Show running status | | bash service.sh logs | Tail live logs |

Feishu Commands

All commands support Chinese aliases:

| Command | Chinese | Description | |---------|---------|-------------| | /help | /帮助 /指令 | Show help | | /status | /状态 | Service status (model, key, STT, sessions) | | /new | /新对话 /新会话 | Reset workspace session | | /model name | /模型 name /切换模型 name | Switch model | | /apikey key | /密钥 key /换key key | Update API key (DM only) | | /stop | /终止 /停止 | Kill running agent task | | /memory | /记忆 | Memory system status | | /memory query | /记忆 关键词 | Semantic search memories | | /log text | /记录 内容 | Write to today's daily log | | /reindex | /整理记忆 | Rebuild memory index | | /task | /任务 /cron /定时 | View/manage scheduled tasks | | /heartbeat | /心跳 | View/manage heartbeat system |

Project routing: projectname: your message routes to a specific workspace.

Voice Recognition

Two-tier STT with automatic fallback:

| Engine | Quality | Notes | |--------|---------|-------| | Volcengine Doubao | Excellent (Chinese) | Primary. Requires Volcengine account | | Local whisper-cpp | Basic | Fallback. Install via brew install whisper-cpp |

Volcengine uses the streaming speech recognition API via WebSocket binary protocol — optimized for short voice messages (5-60s).

Configuration

Copy .env.example to .env and fill in your values:

| Variable | Required | Description | |----------|----------|-------------| | CURSOR_API_KEY | Yes | Cursor Dashboard → Integrations → User API Keys | | FEISHU_APP_ID | Yes | Feishu app ID | | FEISHU_APP_SECRET | Yes | Feishu app secret | | CURSOR_MODEL | No | Default: opus-4.6-thinking | | VOLC_STT_APP_ID | No | Volcengine app ID (skip to disable cloud STT) | | VOLC_STT_ACCESS_TOKEN | No | Volcengine access token | | VOLC_EMBEDDING_API_KEY | No | Volcengine embedding API key (for memory vector search) | | VOLC_EMBEDDING_MODEL | No | Default: doubao-embedding-vision-250615 |

Feishu Bot Setup

1. Create an app at Feishu Open Platform
2. Add Bot capability
3. Permissions: im:message, im:message.group_at_msg, im:resource
4. Events: subscribe to im.message.receive_v1 via WebSocket mode (long connection)

Project Routing

Create ../projects.json (one level up from the bot directory):

{
  "projects": {
    "mycode": { "path": "/path/to/code/project", "description": "Code project" },
    "strategy": { "path": "/path/to/strategy/docs", "description": "Strategy workspace" }
  },
  "default_project": "mycode"
}

Then in Feishu: strategy: 帮我审阅这份季度规划 routes to the strategy workspace.

Memory & Identity System

Inspired by OpenClaw, the bot includes a full identity + memory framework that gives your AI persistent personality and long-term memory.

Architecture

Like OpenClaw, all identity/personality/rules are injected at session start. In our case, Cursor's .mdc rules with alwaysApply: true serve as the injection mechanism — no server-side prompt manipulation needed.

templates/                        Shipped with the repo (factory defaults)
├── AGENTS.md                     Workspace instructions (Cursor auto-loads)
└── .cursor/
    ├── SOUL.md                   AI personality and principles
    ├── IDENTITY.md               Name, emoji, temperament
    ├── USER.md                   Owner profile and preferences
    ├── BOOTSTRAP.md              First-run ceremony (deleted after completion)
    ├── BOOT.md                   Startup self-check (runs on every server start)
    ├── MEMORY.md                 Long-term memory skeleton
    ├── HEARTBEAT.md              Heartbeat checklist template
    ├── TASKS.md                  Scheduled tasks documentation
    ├── TOOLS.md                  Capability list and tool notes
    └── rules/                    Cursor rules (auto-loaded every session)
        ├── soul.mdc              Personality, principles, style
        ├── agent-identity.mdc    Identity metadata + Feishu output limits
        └── ...                   (8 more rule files)

~/your-workspace/                 User's actual workspace (auto-initialized)
├── AGENTS.md                     Workspace instructions (Cursor auto-loads from root)
├── .cursor/
│   ├── SOUL.md                   Customized personality
│   ├── IDENTITY.md               AI's chosen identity
│   ├── USER.md                   Owner's real info
│   ├── MEMORY.md                 Real memories (AI-maintained)
│   ├── HEARTBEAT.md              Heartbeat checklist (AI auto-managed)
│   ├── BOOT.md                   Startup checklist
│   ├── TASKS.md                  Task documentation
│   ├── TOOLS.md                  Capability notes
│   ├── memory/                   Daily logs (YYYY-MM-DD.md)
│   │   └── heartbeat-state.json  Heartbeat check history
│   ├── sessions/                 Conversation transcripts (YYYY-MM-DD.jsonl)
│   └── rules/*.mdc              Customized rules (auto-loaded)
├── .memory.sqlite                Vector embeddings database
└── cron-jobs.json                Scheduled tasks (AI-writable)

How It Works

1. First run: server.ts auto-copies rule templates + .cursor/BOOTSTRAP.md to workspace; first conversation triggers the "birth ceremony" where AI chooses its name and personality
2. Every server start: .cursor/BOOT.md runs once for self-checks and optional online notification
3. Every session: Cursor CLI auto-loads all .mdc rules — identity, personality, safety, tools, and constraints in context from the start
4. Memory recall: before answering about past work/decisions/preferences, AI searches .cursor/MEMORY.md + .cursor/memory/*.md (enforced by memory-protocol.mdc)
5. Memory flush: during long conversations, AI proactively saves key info to files before context overflow
6. After each reply: user message + assistant reply logged to session history
7. Incremental indexing: only re-embeds files that have actually changed (tracked by content hash)
8. Full workspace indexing: all text files in the workspace are indexed (.md, .txt, .html, .json, .mdc, etc.)
9. Heartbeat state: .cursor/memory/heartbeat-state.json tracks check history to avoid redundant work
10. Feishu commands: /memory, /log, /reindex for manual memory operations

Customization

Edit the `.cursor/ru