Content
# Tool List
Interact with your local Claude Code directly within Feishu.
WebSocket long connection, streaming card output, code review, debug, and ask questions on your phone anytime.
> Reuse Claude Max/Pro subscription, no API Key needed, no public IP required.
## Features
**Core Capabilities**
- **Streaming Card Output** — Claude outputs as it thinks, tool call progress visible in real-time, not waiting for a long time
- **Session Cross-Device** — Conversation started on phone, continue on computer; CLI terminal sessions can be resumed in Feishu
- **Image Recognition** — Directly send screenshots to Claude for analysis
- **Slash Commands** — Switch models, restore sessions, check usage, and manage work directories
- **Skills Passthrough** — `/commit`, `/review`, etc. Claude Code Skills directly usable in Feishu
**Group Chat Support (beta)**
- Add bot to group, **@bot** to chat, messages without @ ignored
- Each group has independent session, model, work directory, and private chat without interference
- `/ws` command binds different project directories to different groups, multiple groups concurrent without blocking
**Easy Deployment**
- **No Public IP Needed** — Feishu WebSocket long connection, deploy on home Mac
- **Zero Extra Cost** — Directly call local `claude` CLI, reuse existing subscription
- **Watchdog Self-Healing** — 4-hour automatic restart, prevent WebSocket connection from dying
## Quick Start
### Prerequisites
| Dependency | Minimum Version | Verification Command |
|------------|-----------------|----------------------|
| Python | 3.11+ | `python3 --version` |
| Claude Code CLI | Latest | `claude --version` |
| Claude Max/Pro Subscription | — | `claude "hi"` should respond normally |
### Installation and Launch
```bash
git clone https://github.com/joewongjc/feishu-claude-code.git
cd feishu-claude-code
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env, fill in Feishu app credentials (see "Feishu App Configuration" below)
python main.py
```
Expected output:
```
🚀 Feishu Claude Bot starting...
App ID : cli_xxx...
✅ Connected to Feishu WebSocket long connection (auto-reconnect)...
```
> Users upgrading from old versions can run `python migrate_sessions.py` to migrate session data (automatically backed up).
## Command Reference
**Session Management**
| Command | Description |
|---------|-------------|
| `/new` | Start new session |
| `/resume` | View history sessions |
| `/resume <number>` | Resume specified session |
| `/stop` | Stop current running task |
| `/status` | Current session information |
**Model and Mode**
| Command | Description |
|---------|-------------|
| `/model opus` | Switch model (opus / sonnet / haiku) |
| `/mode bypass` | Switch permission mode |
**Work Directory**
| Command | Description |
|---------|-------------|
| `/cd ~/project` | Switch work directory |
| `/ls` | View current work directory content |
| `/ws save <name> <path>` | Save named workspace |
| `/ws use <name>` | Bind current group/chat to workspace |
**Information Query**
| Command | Description |
|---------|-------------|
| `/usage` | View Claude Max usage (macOS) |
| `/skills` | List Claude Skills |
| `/mcp` | List MCP Servers |
| `/help` | Help |
**Skills Passthrough**
`/commit` etc. unregistered slash commands will be forwarded to Claude CLI for execution.
## Architecture
```
┌──────────┐ WebSocket ┌────────────────┐ subprocess ┌────────────┐
│ Feishu App │◄───────────►│ feishu-claude │─────────────►│ claude CLI │
│ (User) │ long connection │ (main.py) │ stream-json │ (local) │
└──────────┘ └────────────────┘ └────────────┘
```
Feishu pushes messages to local process via WebSocket, process calls `claude` CLI's `--print --output-format stream-json` mode for streaming output, and updates content in real-time through Feishu card message patch API.
## Feishu App Configuration
### 1. Create App
1. Open [Feishu Open Platform](https://open.feishu.cn/app), click "Create Enterprise Self-Built App"
2. Fill in app name (e.g., `Claude Code`), select icon, click create
### 2. Add Bot Capability
1. Enter app details, select "Add App Capability" on the left menu
2. Add "Bot" capability
### 3. Enable Permissions
Enter "Permission Management" page, search and enable the following permissions:
| Permission scope | Description |
|-----------------|-------------|
| `im:message` | Get and send single chat/group messages |
| `im:message:send_as_bot` | Send messages as app identity |
| `im:resource` | Get message resource files (images, etc.) |
### 4. Enable Long Connection Mode
1. Left menu "Events and Callbacks" → "Event Configuration"
2. Select subscription method "Receive events using long connection" (not Webhook)
3. Add event: `im.message.receive_v1` (receive messages)
### 5. Get Credentials
1. Enter "Credentials and Basic Information" page
2. Copy App ID and App Secret, fill in `.env` file
### 6. Publish App
1. Click "Version Management and Release" → "Create Version"
2. Fill in version number and update description, submit for review
3. Administrator reviews and approves in Feishu management backend for use
## Environment Variables
| Variable | Required | Default Value | Description |
|----------|----------:|---------------|-------------|
| `FEISHU_APP_ID` | Yes | — | Feishu app App ID |
| `FEISHU_APP_SECRET` | Yes | — | Feishu app App Secret |
| `DEFAULT_MODEL` | No | `claude-sonnet-4-6` | Default Claude model used |
| `DEFAULT_CWD` | No | `~` | Claude CLI's default work directory |
| `PERMISSION_MODE` | No | `bypassPermissions` | Tool permission mode |
| `STREAM_CHUNK_SIZE` | No | `20` | Streaming push character accumulation threshold |
| `CLAUDE_CLI_PATH` | No | auto-detect | Claude CLI executable file path |
## Persistent Deployment
### macOS (launchctl)
```bash
cp deploy/feishu-claude.plist ~/Library/LaunchAgents/com.feishu-claude.bot.plist
# Modify plist's /path/to/ to actual path
launchctl load ~/Library/LaunchAgents/com.feishu-claude.bot.plist
launchctl list | grep feishu-claude
tail -f /tmp/feishu-claude.log
```
### Linux (systemd)
```bash
sudo cp deploy/feishu-claude.service /etc/systemd/system/
# Modify service's path and User
sudo systemctl daemon-reload
sudo systemctl enable feishu-claude
sudo systemctl start feishu-claude
journalctl -u feishu-claude -f
```
## License
[MIT](LICENSE
