_____          _   _           _           ____        _   
  / ____|        | | | |         | |         |  _ \      | |  
 | |     ___   __| | | |__   __ _| |_ _   _  | |_) | ___ | |_ 
 | |    / _ \ / _` | | '_ \ / _` | __| | | | |  _ < / _ \| __|
 | |___| (_) | (_| | | |_) | (_| | |_| |_| | | |_) | (_) | |_ 
  \_____\___/ \__,_| |_.__/ \__,_|\__|\__, | |____/ \___/ \__|
                                       __/ |                  
                                      |___/                    

English | 中文

Multi-Channel AI Assistant - A multi-platform messaging bot built on CodeBuddy CLI.

Extend the powerful AI capabilities of CodeBuddy to multiple communication platforms, making AI assistants accessible everywhere.

• 🔌 Multi-Channel Support - Telegram, Discord, Slack, Feishu, DingTalk, QQ, WhatsApp, Email, Mochat
• 🧠 AI-Powered - Built on CodeBuddy CLI, supporting multiple models (Claude, etc.)
• 💾 Session Management - Automatic multi-user session management with conversation context support
• 📁 Workspace - Each bot instance has its own independent workspace and memory system
• 🔐 Access Control - Supports whitelist, mention trigger, and various other policies
• 🔄 Thinking Mode - Optional AI thinking process display
• ⚡ Streaming Output - Real-time streaming output support for Telegram and DingTalk AI Card

codebuddy-bot depends on CodeBuddy CLI. Please install it first:

# With Node.js 22+
npm install -g @codebuddy-ai/codebuddy-cli

# Or visit the official documentation
# https://www.codebuddy.cn/docs/cli/installation

codebuddy login

Follow the prompts to complete the login process.

Option 1: pip install (Recommended)

pip install codebuddy-bot

After installation, you can use it directly:

codebuddy-bot --help
codebuddy-bot init
codebuddy-bot gateway start

Option 2: Install from Source

# Clone repository
git clone https://github.com/your-repo/codebuddy-bot.git
cd codebuddy-bot

# Install dependencies (using uv)
uv sync

# Create default config file (pip install)
codebuddy-bot init

# Or from source
uv run codebuddy-bot init

# Or manually
mkdir -p ~/.codebuddy-bot
cp config/config.example.json ~/.codebuddy-bot/config.json

After pip install:

# Foreground (debug mode)
codebuddy-bot gateway run

# Background
codebuddy-bot gateway start

# Check status
codebuddy-bot status

# Stop service
codebuddy-bot gateway stop

After source install:

# Foreground (debug mode)
uv run codebuddy-bot gateway run

# Background
uv run codebuddy-bot gateway start

Configuration file located at ~/.codebuddy-bot/config.json

{
  "driver": {
    "codebuddy_path": "codebuddy",
    "model": "claude-sonnet-4-20250514",
    "permission_mode": "bypassPermissions",
    "thinking": false,
    "max_turns": 40,
    "timeout": 300,
    "workspace": "~/.codebuddy-bot/workspace",
    "extra_args": []
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": []
    },
    "discord": {
      "enabled": false,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": []
    },
    "slack": {
      "enabled": false,
      "bot_token": "xoxb-xxx",
      "app_token": "xapp-xxx",
      "allow_from": [],
      "group_policy": "mention"
    },
    "feishu": {
      "enabled": false,
      "app_id": "cli_xxx",
      "app_secret": "xxx",
      "encrypt_key": "",
      "verification_token": "",
      "allow_from": []
    },
    "dingtalk": {
      "enabled": false,
      "client_id": "xxx",
      "client_secret": "xxx",
      "robot_code": "xxx",
      "card_template_id": "xxx-xxx-xxx",
      "card_template_key": "content",
      "allow_from": []
    },
    "qq": {
      "enabled": false,
      "app_id": "xxx",
      "secret": "xxx",
      "allow_from": []
    },
    "whatsapp": {
      "enabled": false,
      "bridge_url": "http://localhost:3001",
      "bridge_token": "",
      "allow_from": []
    },
    "email": {
      "enabled": false,
      "consent_granted": false,
      "imap_host": "imap.gmail.com",
      "imap_port": 993,
      "imap_username": "your@email.com",
      "imap_password": "app_password",
      "smtp_host": "smtp.gmail.com",
      "smtp_port": 587,
      "smtp_username": "your@email.com",
      "smtp_password": "app_password",
      "from_address": "your@email.com",
      "allow_from": [],
      "auto_reply_enabled": true
    },
    "mochat": {
      "enabled": false,
      "base_url": "https://mochat.io",
      "socket_url": "https://mochat.io",
      "socket_path": "/socket.io",
      "claw_token": "xxx",
      "agent_user_id": "",
      "sessions": ["*"],
      "panels": ["*"]
    }
  },
  "log_level": "INFO",
  "log_file": ""
}

Parameter	Type	Default	Description
codebuddy_path	string	"codebuddy"	CodeBuddy CLI path
model	string	"claude-sonnet-4-20250514"	Default model
permission_mode	string	"bypassPermissions"	Permission mode: default, acceptEdits, plan, bypassPermissions
thinking	bool	false	Show AI thinking process
max_turns	int	40	Maximum conversation turns per session
timeout	int	300	Timeout in seconds
workspace	string	~/.codebuddy-bot/workspace	Workspace path
extra_args	list	[]	Additional CodeBuddy arguments

Mode	Description
default	All operations require confirmation
acceptEdits	Auto-approve file edits
plan	Plan mode, read-only
bypassPermissions	Skip all permission checks (recommended for bots)

For detailed channel configuration, please refer to the specific channel documentation.

# Show version
codebuddy-bot version
codebuddy-bot -v

# Show help
codebuddy-bot --help

# Check status
codebuddy-bot status

# Initialize config
codebuddy-bot init

# Start service in background
codebuddy-bot gateway start

# Run in foreground (debug mode)
codebuddy-bot gateway run

# Stop service
codebuddy-bot gateway stop

# Restart service
codebuddy-bot gateway restart

# Show config
codebuddy-bot config

# Switch model
codebuddy-bot model claude-sonnet-4-20250514

# Thinking mode
codebuddy-bot thinking on
codebuddy-bot thinking off

# List all sessions
codebuddy-bot sessions

# Clear session
codebuddy-bot clear-session telegram 123456

# List tasks
codebuddy-bot cron list

# Add interval task
codebuddy-bot cron add --name "Water reminder" --message "Time to drink water!" --every 300

# Add one-time task
codebuddy-bot cron add --name "Meeting reminder" --message "Meeting time!" --at "2024-12-25T10:00:00"

# Add cron expression task
codebuddy-bot cron add --name "Morning report" --message "Send morning report" --cron "0 9 * * *"

# Enable/disable task
codebuddy-bot cron enable <id>
codebuddy-bot cron disable <id>

# Run task immediately
codebuddy-bot cron run <id>

# Remove task
codebuddy-bot cron remove <id>

# CodeBuddy basic passthrough
codebuddy-bot codebuddy --help
codebuddy-bot codebuddy -p "hello"

# MCP commands
codebuddy-bot mcp --help

# Agent commands
codebuddy-bot agent --help

~/.codebuddy-bot/
├── config.json              # Configuration file
├── gateway.pid              # PID file (background mode)
├── gateway.log              # Gateway log
├── session_mappings.json    # Session mappings
└── workspace/               # CodeBuddy workspace
    ├── AGENTS.md            # Agent behavior guide
    ├── BOOT.md              # Boot configuration
    ├── HEARTBEAT.md         # Heartbeat tasks
    ├── IDENTITY.md          # Identity
    ├── SOUL.md              # AI personality definition
    ├── TOOLS.md             # Tool configuration
    ├── USER.md              # User info
    └── memory/              # Memory directory
        └── MEMORY.md        # Long-term memory

codebuddy-bot/
├── codebuddy_bot/
│   ├── __init__.py
│   ├── __main__.py          # Entry point
│   ├── bus/                 # Message bus
│   │   ├── events.py        # Event definitions
│   │   └── queue.py         # Message queue
│   ├── channels/            # Channel implementations
│   │   ├── base.py          # Base class
│   │   ├── telegram.py
│   │   ├── discord.py
│   │   ├── slack.py
│   │   ├── feishu.py
│   │   ├── dingtalk.py
│   │   ├── qq.py
│   │   ├── whatsapp.py
│   │   ├── email.py
│   │   ├── mochat.py
│   │   └── manager.py       # Channel manager
│   ├── cli/                 # CLI commands
│   │   └── commands.py
│   ├── config/              # Configuration management
│   │   ├── schema.py        # Configuration model
│   │   └── loader.py
│   ├── cron/                # Scheduled tasks
│   │   ├── service.py
│   │   └── types.py
│   ├── engine/              # Core engine
│   │   ├── adapter.py       # CodeBuddy SDK adapter
│   │   └── loop.py          # Message loop
│   ├── heartbeat/           # Heartbeat service
│   │   └── service.py
│   ├── session/             # Session management
│   │   └── manager.py
│   ├── templates/           # Template files
│   │   ├── AGENTS.md
│   │   ├── SOUL.md
│   │   └── ...
│   └── utils/               # Utility functions
│       └── helpers.py
├── tests/
├── pyproject.toml
└── README.md

Issues and Pull Requests are welcome!

MIT

• CodeBuddy CLI - Powerful AI Agent CLI