PhoneWork/README.md

PhoneWork

Feishu bot integration with Claude Code CLI.

Architecture

┌─────────────┐    WebSocket     ┌──────────────┐    LangChain     ┌─────────────┐
│   Feishu    │ ◄──────────────► │   FastAPI    │ ◄──────────────► │  LLM API    │
│   (client)  │                  │   (server)   │                  │ (OpenAI)    │
└─────────────┘                  └──────────────┘                  └─────────────┘
                                        │
                                        ▼
                                 ┌─────────────┐
                                 │ Claude Code │
                                 │   (PTY)     │
                                 └─────────────┘

Components:

Module	Purpose
main.py	FastAPI entry point, starts WebSocket client + session manager
bot/handler.py	Receives Feishu events, dispatches to orchestrator
bot/feishu.py	Sends replies back to Feishu chats
orchestrator/agent.py	LangChain agent with per-user history + active session tracking
orchestrator/tools.py	Tools: create_conversation, send_to_conversation, close_conversation
agent/manager.py	Session registry with idle timeout reaper
agent/pty_process.py	Runs claude -p headlessly, manages session continuity

Flow: User message → Feishu WebSocket → Handler → Orchestrator (LLM decides action) → Tool → Session Manager → Claude Code PTY → Response back to Feishu

Setup

1. Feishu App: Create at https://open.feishu.cn

   • Enable Bot capability + long-connection event subscription
   • Get FEISHU_APP_ID and FEISHU_APP_SECRET

2. LLM Endpoint: Configure OpenAI-compatible endpoint

   • OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL

3. Claude Code CLI: Install and authenticate claude command

4. Configuration:

   cp keyring.example.yaml keyring.yaml
   # Edit keyring.yaml with your credentials
   

5. Run:

   pip install -r requirements.txt
   python main.py
   

Requirements: Python 3.11+