feishu-notify

飞书 (Lark) 机器人消息推送与远程控制。支持从飞书远程操控 Claude Code 或其他终端。

English | 中文

---

Features

• 🔔 Instant Push - Auto-notify on task completion
• 🎮 Remote Control - Send commands from Feishu to terminal
• 🪟 Multi-window - On-duty mode for window management
• 📱 Mobile Friendly - Optimized output for mobile reading
• 🎴 Interactive Cards - Window list with card display
• 🌐 i18n - Chinese and English support

Installation

# From PyPI (recommended)
pip install feishu-notify

# From source
git clone https://github.com/steptian/feishu-notify.git
cd feishu-notify
pip install -e .

Quick Start

1. Configure Feishu App

1. Visit Feishu Open Platform to create an app
2. Get App ID and App Secret
3. Configure permissions: im:message, im:message:send_as_bot
4. Publish the app and add to a group chat

2. Set Environment Variables

# Create config directory
mkdir -p ~/.config/feishu-notify

# Create .env file
cat > ~/.config/feishu-notify/.env << 'EOF'
FEISHU_APP_ID=cli_xxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxx
EOF

chmod 600 ~/.config/feishu-notify/.env

3. Start Long Polling Client

feishu-notify start

Or run directly:

python -m feishu_notify.client

4. Configure Claude Code Hook (Optional but Recommended)

Edit ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "feishu-notify hook"
          }
        ]
      }
    ]
  }
}

Usage

From Feishu

Send messages directly (no prefix needed):

帮我写一个冒泡排序
今天上海天气怎么样？

Window management:

/windows          # View active windows (interactive card)
/switch 1         # Switch to window 1
/on-duty          # View current on-duty window

In Claude Code

feishu-notify send "Title" "Content"    # Send custom notification
feishu-notify send "Task done"          # Send simple notification
feishu-notify test                       # Test push
feishu-notify config --check             # Validate configuration

Command Line

feishu-notify send "Title" "Content"    # Send notification
feishu-notify test                       # Test
feishu-notify config --check             # Check config

As a Python Library

from feishu_notify import send_to_feishu, Config

# Load config from environment
config = Config.from_env()
config.validate()

# Send message
send_to_feishu("Hello from Python!", config=config)

Architecture

┌─────────────┐                    ┌─────────────┐
│  Feishu App │◄────WebSocket────►│   Client    │
└─────────────┘                    └──────┬──────┘
                                          │
                                          ▼
                                   ┌─────────────┐
                                   │ tmux session│
                                   │(Claude Code)│
                                   └─────────────┘
                                          ▲
                                          │
                                   ┌──────┴──────┐
                                   │  Stop Hook  │
                                   │ (auto-reply)│
                                   └─────────────┘

File Structure

feishu-notify/
├── src/feishu_notify/
│   ├── __init__.py
│   ├── cli.py           # CLI entry point
│   ├── client.py        # WebSocket client
│   ├── config.py        # Configuration management
│   ├── sender.py        # Message sending
│   └── i18n.py          # Internationalization
├── tests/
│   ├── test_config.py
│   └── test_sender.py
├── skills/              # Claude Code Skill
│   └── feishu-notify/
│       └── SKILL.md
├── pyproject.toml
└── README.md

Configuration

Environment Variables

Variable	Required	Description
FEISHU_APP_ID	✅	Feishu App ID
FEISHU_APP_SECRET	✅	Feishu App Secret
FEISHU_WEBHOOK_URL	❌	Group bot webhook (for simple push)
FEISHU_NOTIFY_LANG	❌	Language: zh (default) or en

Multi-window Scenario

When you have multiple Claude Code windows, use on-duty mode:

1. In Claude Code terminal: feishu-notify on-duty
2. Messages from Feishu will only go to the on-duty window
3. Switch windows: Send /windows in Feishu → Click to switch

Troubleshooting

Message Send Failed

1. Check .env configuration is correct
2. Check if Feishu app is published
3. Check if app is added to group chat

Reply Not Sent to Feishu

1. Confirm Stop Hook is configured
2. Confirm long polling client is running
3. Check logs: tail -f /tmp/feishu-longpoll.log

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=feishu_notify

# Type check
pyright src/

License

MIT

---

中文文档

飞书机器人消息推送与远程控制 Skill，支持从飞书远程操控 Claude Code。

特性

• 🔔 即时推送 - 任务完成自动通知到飞书
• 🎮 远程控制 - 从飞书发送命令到 Claude Code
• 🪟 多窗口管理 - 值班模式，指定窗口接收消息
• 📱 手机友好 - 输出优化，适合手机阅读
• 🎴 交互卡片 - 窗口列表卡片展示

安装

pip install feishu-notify

快速开始

1. 配置飞书应用并获取 App ID 和 App Secret
2. 创建 ~/.config/feishu-notify/.env 文件
3. 运行 feishu-notify start 启动长连接客户端

使用方式

从飞书发消息（无需前缀）：

帮我写一个冒泡排序
今天上海天气怎么样？

窗口管理：

/windows          # 查看活跃窗口
/switch 1         # 切换到窗口 1
/on-duty          # 查看当前值班窗口

故障排除

消息发送失败

1. 检查 .env 配置是否正确
2. 检查飞书应用是否已发布
3. 检查应用是否已添加到群聊

回复没有发送到飞书

1. 确认 Stop Hook 已配置
2. 确认长连接客户端正在运行
3. 检查日志：tail -f /tmp/feishu-longpoll.log

许可证

MIT