feishu-agent

# Feishu Agent Skill

**Feishu (Lark) CLI agent** - Provides calendar, todo, and contact management capabilities for AI assistants.

## Installation

```bash
# Install via clawhub
clawhub install feishu-agent

# Or run directly with bunx
bunx @teamclaw/feishu-agent <command>

# Or install globally via bun
bun add -g @teamclaw/feishu-agent
feishu-agent <command>
```

## Quick Start

1. **Setup** - Configure Feishu app credentials:
   ```bash
   feishu-agent setup
   ```

2. **Authenticate** - OAuth 2.0 authorization:
   ```bash
   feishu-agent auth
   ```

3. **Start using** - Check your calendar:
   ```bash
   feishu-agent calendar events
   ```

## Capabilities

- 📅 **Calendar**: List calendars, view events, create/delete events with automatic conflict detection
- ✅ **Todo**: Manage tasks via Feishu Bitable
- 👥 **Contacts**: Search and list users from organization
- 🔐 **Auth**: OAuth 2.0 authentication with automatic token refresh

## Commands

### Setup & Auth

| Command | Description |
|---------|-------------|
| `feishu-agent setup` | Interactive setup wizard (App credentials + OAuth + Bitable) |
| `feishu-agent auth` | OAuth 2.0 authorization to get user_access_token |
| `feishu-agent whoami` | Show current user and authorization status |
| `feishu-agent config list` | View global configuration |

### Calendar Management

| Command | Description |
|---------|-------------|
| `feishu-agent calendar` | List all calendars (primary, subscribed) |
| `feishu-agent calendar events` | List events in primary calendar |
| `feishu-agent calendar create --summary "Meeting" --start "2026-03-05 14:00" --end "2026-03-05 15:00"` | Create a new event (auto-checks conflicts) |
| `feishu-agent calendar create --summary "Meeting" --start "..." --end "..." --attendee user_id` | Create event with attendees |
| `feishu-agent calendar delete --event-id=evt123` | Delete an event |

### Other Features

| Command | Description |
|---------|-------------|
| `feishu-agent todo list` |...

# Feishu Agent

Feishu Agent is a TypeScript/Node.js middleware layer for Feishu (Lark) API integration, designed for AI assistants.

## Features

- 📅 Calendar management (list calendars, events, create/delete events)
- ⚠️ **Automatic conflict detection** when creating events (uses FreeBusy API)
- ✅ Todo management via Bitable
- 👥 Contact management (list users, search by name/email)
- 🔐 OAuth 2.0 authentication with auto token refresh
- 🚀 CLI interface with commander

## Installation

### Global Install (Recommended)

```bash
bun add -g @teamclaw/feishu-agent
```

After installation, you can use the `feishu_agent` command directly:

```bash
feishu_agent calendar list
```

### Run with bunx (No Install)

```bash
bunx @teamclaw/feishu-agent calendar list
```

### Local Development

```bash
bun install
```

## Quick Start

### 1. Setup

Run the setup command to configure your Feishu app credentials:

```bash
feishu_agent setup
```

Or export environment variables:
```bash
export FEISHU_APP_ID=cli_xxx
export FEISHU_APP_SECRET=xxx
```

### 2. Authenticate

```bash
feishu_agent auth
```

This will open a browser window for OAuth 2.0 authorization.

## Usage

### Calendar

```bash
# List calendars
feishu_agent calendar list

# List events
feishu_agent calendar events

# Create event (automatically checks for time conflicts)
feishu_agent calendar create --summary "Meeting" --start "2026-03-01 14:00" --end "2026-03-01 15:00"

# Create event with attendees
feishu_agent calendar create --summary "Meeting" --start "2026-03-01 14:00" --end "2026-03-01 15:00" --attendee-name "张三"

# Delete event
feishu_agent calendar delete --event-id "xxx"
```

### Todo

```bash
# List todos (requires FEISHU_BASE_TOKEN env)
feishu_agent todo list

# Create todo
feishu_agent todo create --title "Task" --priority "High"

# Mark todo as done
feishu_agent todo done --record-id "xxx"
```

### Contact

```bash
# List users
feishu_agent contact list --dept "0"

# Search users
feishu_agent conta...