clibot

clibot is a lightweight middleware that bridges AI CLI tools (Claude Code, Codex, Gemini CLI, OpenCode) to IM platforms (Discord, Telegram, Feishu, DingTalk, QQ, WeChat). Use powerful desktop AI programming assistants from your phone with streaming responses - no public IP required.

✨ Features

🌍 No Public IP Required: All bots connect via long-connections (WebSocket/Long Polling). Deploy on your home/office computer behind NAT.
📱 Access Anywhere: Use desktop AI tools from mobile phone via IM apps
🎯 Unified Entry Point: Manage multiple AI tools through a single bot
🔌 Flexible Extension: Add new CLI or Bot by implementing interfaces
⚡ ACP Support: Streaming responses, no tmux required (for compatible CLIs)
🔄 Session Switch: Switch session adapter mode on-the-fly (e.g. claude ACP ↔ claude stdio) with conversation resume
📋 Session Templates: Create sessions instantly with sn claude|codex|gemini <dir> — zero config
💾 Session Persistence: Dynamic sessions survive restarts with automatic state restore
✂️ Auto Message Split: Long responses auto-split by line with rune-aware counting
🔒 Idle Auto-Cleanup: Inactive dynamic sessions are automatically cleaned up
🤖 Yolo Mode: Skip permission prompts for trusted sessions

✨ Claude Code Skill

For Claude Code users, an interactive skill is available for one-command setup:

/clibot setup

The skill handles everything: binary download, bot token setup, config generation, and service startup — all through a guided wizard. No manual config editing required.

See skills/clibot/ for details.

🚀 Quick Start

Prerequisites

Bot Account (Feishu/Discord/Telegram)
ACP-Compatible CLI (e.g., claude-agent-acp) OR tmux (for Hook Mode)

For detailed installation instructions, see INSTALL.md.

Install

Linux / macOS:

curl -sL https://raw.githubusercontent.com/keepmind9/clibot/main/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/keepmind9/clibot/main/scripts/install.ps1 | iex

From source (requires Go 1.24+):

go install github.com/keepmind9/clibot@latest

Update

clibot update          # Download latest version
clibot update --apply  # Apply the downloaded update

🌐 Network Proxy

clibot supports network proxies for accessing IM platforms in restricted networks.

Quick Setup

# Using environment variables
export HTTP_PROXY="http://127.0.0.1:7890"
clibot serve

# Or configure in config.yaml
proxy:
  enabled: true
  url: "http://127.0.0.1:7890"

Supported Protocols

HTTP/HTTPS proxy
SOCKS5 proxy
Optional username/password authentication

Documentation

See Proxy Configuration Guide for details.

🔑 Get Your User ID

Before configuring clibot, you need to get your user ID from the IM platform for whitelist and admin setup.

Quick Method

Step 1: Start clibot with whitelist temporarily disabled:

# ~/temp_config.yaml
security:
  whitelist_enabled: false  # Temporarily disable

bots:
  telegram:
    enabled: true
    token: "YOUR_BOT_TOKEN"

Step 2: Run clibot:

clibot serve --config ~/temp_config.yaml

Step 3: Send echo command to your bot:

echo

Step 4: Bot replies with your user ID:

🔍 Your IM Information

Platform: telegram
User ID: 123456789

Step 5: Update your actual config with your user ID:

security:
  whitelist_enabled: true
  allowed_users:
    telegram:
      - "123456789"  # Your actual user ID
  admins:
    telegram:
      - "123456789"  # Your actual user ID

Important: Delete ~/temp_config.yaml and restart with proper config.

Configure

# Create config directory
mkdir -p ~/.config/clibot

# Copy configuration template
cp configs/config.mini.yaml ~/.config/clibot/config.yaml

# Edit configuration (replace YOUR_* placeholders)
nano ~/.config/clibot/config.yaml

Run

clibot serve --config ~/.config/clibot/config.yaml

💡 Operation Modes

ACP Mode (Recommended) ⭐

Best for: claude-agent-acp, Gemini CLI with ACP, OpenCode with ACP

Advantages:

✅ No tmux required
✅ Streaming responses (real-time)
✅ Full-duplex communication
✅ Works on all platforms

Configuration:

sessions:
  - name: "my-project"
    work_dir: "/path/to/project"
    start_cmd: "claude-agent-acp"
    transport: "stdio://"

Setup ACP CLI:

# Install ACP adapter for Claude Code
npm install -g @zed-industries/claude-agent-acp

# Gemini CLI
gemini --experimental-acp

# OpenCode CLI
opencode --acp

Hook Mode

Best for: Claude Code, Gemini CLI, OpenCode (default mode)

Advantages:

✅ Real-time notifications
✅ Accurate completion detection

Requirements:

⚠️ Requires tmux
⚠️ Requires CLI hook configuration

Configuration:

sessions:
  - name: "my-project"
    work_dir: "/path/to/project"
    start_cmd: "claude"

See CLI Hook Configuration Guide for detailed setup.

Mode Selection

Priority: ACP > Hook > Stdio

ACP Mode provides better user experience and should be preferred when available.

Stdio Mode (Zero Config)

Best for: Codex, Gemini, OpenCode, Claude Code — when you want zero setup

Advantages:

✅ No tmux required
✅ No hook configuration required
✅ Works with any CLI that supports JSON output

How it works: Per-turn CLIs (Codex, Gemini, OpenCode) spawn a new process for each message. Claude-stdio keeps a long-lived process with bidirectional JSON communication. Session resume is supported via session IDs.

Configuration:

sessions:
  - name: "codex"
    cli_type: "codex-stdio"
    work_dir: "/path/to/project"

cli_adapters:
  codex-stdio:
    timeout: "5m"

Supported CLI types: codex-stdio, gemini-stdio, opencode-stdio (per-turn), claude-stdio (persistent)

📱 Setup Bot

Feishu (Recommended)

Create a Feishu app at Open Platform
Get App ID and App Secret
Configure bot:

bots:
  feishu:
    enabled: true
    app_id: "cli_xxxxxxxxx"
    app_secret: "xxxxxxxxxxxxxxxx"
    # reply_mode: "card"          # Streaming card reply with typewriter effect (default: "text")
    # debounce_ms: 2000           # Merge rapid messages within window (0 = disabled)
    # mention_in_group: true      # Only respond when @mentioned in group chats (default: true)
    # media_dir: "~/.clibot/feishu/media"  # Directory for downloaded media
    # media_ttl: "24h"            # Media cache TTL ("0" to disable cleanup)
    # max_media_size: 10485760    # Max media file size in bytes (0 = no limit)

Discord

Create a Discord application at Discord Developer Portal
Create a bot and get token
Invite bot to your server
Configure:

bots:
  discord:
    enabled: true
    token: "YOUR_BOT_TOKEN"
    channel_id: "YOUR_CHANNEL_ID"

Telegram

Create a bot via BotFather
Get bot token
Configure:

bots:
  telegram:
    enabled: true
    token: "YOUR_BOT_TOKEN"

QQ

Create a QQ bot at QQ Open Platform
Get App ID and App Secret
Configure:

bots:
  qq:
    enabled: true
    app_id: "YOUR_QQ_APP_ID"
    app_secret: "YOUR_QQ_APP_SECRET"

Note: QQ bot uses WebSocket for receiving messages and HTTP API for sending. Supports C2C (private chat) messages.

WeChat

WeChat bot uses QR code login instead of a static token. On first run, scan the QR code with your WeChat app to authenticate.

Enable the bot and run clibot:
Scan the QR code when prompted (rendered in terminal)
Click "Confirm" in WeChat to authorize
Credentials are saved automatically for future runs

bots:
  weixin:
    enabled: true
    # Optional: credentials file path (default: ~/.clibot/weixin/credentials.json)
    # credentials_path: "~/.clibot/weixin/credentials.json"

Note: The first login requires scanning the QR code in a terminal with a display. After initial authentication, credentials are stored and reused automatically. Session expiry (code -14) will require re-scanning.

🎮 Usage

Special Commands

slist                              # List all sessions
sn <template> <dir> [name]         # Create session from template (e.g. sn claude ~/project)
snlist                             # List available templates
suse <session>                     # Switch to session
sswitch <session> <cli_type>       # Switch session CLI type with resume (admin only)
snew <name> <type> <dir> [cmd]     # Create new session (admin only)
sdel <name>                        # Delete session (admin only)
sclose [name]                      # Close session
sstatus [name]                     # Show session status
whoami                             # Show your info
status                             # Show all session status
echo                               # Show your IM info
help                               # Show help

Special Keywords

⚠️ Hook Mode Only: These keywords only work in Hook mode with tmux.

tab           # Send Tab key (autocomplete)
esc           # Send Escape key
s-tab         # Send Shift+Tab
enter         # Send Enter key
ctrl-c        # Send Ctrl+C (interrupt)

Note: These keywords simulate key presses via tmux send-keys. They only work in Hook mode. ACP mode uses direct protocol communication and does not support these keywords.

Example Workflow

You:  slist
Bot:  Available Sessions:
     • claude (acp)
     • gemini (gemini)

You:  suse claude
Bot:  ✓ Switched to session: claude

You:  help me write a python function to parse json
Bot:  [AI response...]

🔧 Deployment

Run as systemd service (Linux/macOS)

# Create systemd user directory
mkdir -p ~/.config/systemd/user

# Install service file
cp deploy/clibot.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable clibot
systemctl --user start clibot

# View logs
journalctl --user -u clibot -f

Run as supervisor service

# Install supervisor
sudo apt-get install supervisor

# Install config file
sudo cp deploy/clibot.conf /etc/supervisor/conf.d/
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start clibot

For detailed deployment guide, see deploy/DEPLOYMENT.md.

🔒 Security

⚠️ User whitelist must be enabled (default: whitelist_enabled: true)

Only whitelisted users can use clibot. Always configure allowed_users and admins in your config file.

🏗️ Project Structure

clibot/
├── cmd/                    # CLI entry point
├── internal/
│   ├── core/               # Core logic
│   ├── cli/                # CLI adapters
│   └── bot/                # Bot adapters
├── configs/                # Configuration templates
└── docs/                   # Documentation

📚 Documentation

INSTALL.md - Installation guide
docs/en/setup/cli-hooks.md - CLI hook configuration
deploy/DEPLOYMENT.md - Deployment guide
AGENTS.md - Development guidelines

🤝 Contributing

Contributions are welcome! Please read AGENTS.md for development guidelines.

📄 License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 310 Commits
.github		.github
cmd/clibot		cmd/clibot
configs		configs
deploy		deploy
docs		docs
internal		internal
pkg/constants		pkg/constants
scripts		scripts
skills/clibot		skills/clibot
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
GEMINI.md		GEMINI.md
INSTALL.md		INSTALL.md
INSTALL_zh.md		INSTALL_zh.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README_zh.md		README_zh.md
SECURITY.md		SECURITY.md
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

clibot

✨ Features

✨ Claude Code Skill

🚀 Quick Start

Prerequisites

Install

Update

🌐 Network Proxy

Quick Setup

Supported Protocols

Documentation

🔑 Get Your User ID

Quick Method

Configure

Run

💡 Operation Modes

ACP Mode (Recommended) ⭐

Hook Mode

Mode Selection

Stdio Mode (Zero Config)

📱 Setup Bot

Feishu (Recommended)

Discord

Telegram

QQ

WeChat

🎮 Usage

Special Commands

Special Keywords

Example Workflow

🔧 Deployment

Run as systemd service (Linux/macOS)

Run as supervisor service

🔒 Security

🏗️ Project Structure

📚 Documentation

🤝 Contributing

📄 License

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Contributors

Uh oh!

Languages