Two lines of code to awaken your exclusive agent.

git clone https://github.com/musenming/comobot.git
cd comobot
python3.11 -m venv .venv
# or: python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -e ".[dev]"
# (Optional) Install Matrix channel support
pip install -e ".[matrix]"
comobot --help
comobot --version
pytest tests/ -v

pip install comobot

uv tool install comobot

# Docker Compose (recommended)
docker compose run --rm comobot-cli onboard   # First-time setup
vim ~/.comobot/config.json                     # Add API keys
docker compose up -d comobot-gateway           # Start gateway

# Docker (manual)
docker build -t comobot .
docker run -v ~/.comobot:/root/.comobot --rm comobot onboard
vim ~/.comobot/config.json
docker run -v ~/.comobot:/root/.comobot -p 18790:18790 comobot gateway

Prerequisites

Python (>= 3.11), pip (>= 22.0), Node.js (>= 18), and Git.

Post-Install Setup

comobot onboard

Edit ~/.comobot/config.json and add your provider key:

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "provider": "openrouter"
    }
  }
}

Start chatting:

comobot agent              # Interactive mode
comobot agent -m "Hello!"  # Single message
comobot gateway            # Start gateway (API + channels + web UI)

Web Frontend

Production mode:

cd web
npm install
npm run build
cd ..
comobot gateway

Development mode:

# Terminal 1: Start the backend gateway (API port 18790)
comobot gateway
# Terminal 2: Start Vite dev server (Frontend port 5173, auto-proxies API)
cd web
npm install
npm run dev

Environment Variables & WhatsApp Bridge Setup

cd bridge
npm install
npm run build
comobot channels login

Troubleshooting & Development Commands

ModuleNotFoundError: nh3: run pip install -e ".[matrix]".

ruff check .               # Lint
ruff check . --fix         # Auto-fix lint issues
ruff format .              # Format
pytest tests/ -v           # Run tests