Echo Core

AI-powered personal assistant bot with Discord, Telegram, and WhatsApp bridges. Uses Claude Code CLI for conversation, with persistent sessions, cron scheduling, semantic memory search, and heartbeat monitoring.

Quick Start

# Interactive setup wizard (recommended for first install)
bash setup.sh

The wizard handles prerequisites, virtual environment, bridge tokens, config, and systemd services in 10 guided steps.

Manual Setup

# 1. Create venv and install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 2. Store Discord token in keyring
./cli.py secrets set discord_token

# 3. Edit config.json (bot name, owner ID, channels)

# 4. Start
systemctl --user start echo-core

Architecture

                    ┌─────────────┐
                    │  Claude CLI  │
                    └──────┬──────┘
                           │
                    ┌──────┴──────┐
                    │   Router    │
                    └──────┬──────┘
              ┌────────────┼────────────┐
              │            │            │
        ┌─────┴─────┐ ┌───┴───┐ ┌──────┴──────┐
        │  Discord   │ │Telegram│ │  WhatsApp   │
        │  (d.py)    │ │(ptb)   │ │(Baileys+py) │
        └────────────┘ └────────┘ └─────────────┘

• Discord: slash commands via discord.py
• Telegram: commands + inline keyboards via python-telegram-bot
• WhatsApp: Node.js Baileys bridge + Python polling adapter
• All three run concurrently in the same asyncio event loop

Key Components

Component	Description
src/main.py	Entry point — starts all adapters + scheduler + heartbeat
src/router.py	Routes messages to Claude or handles commands
src/claude_session.py	Claude Code CLI wrapper with --resume sessions
src/credential_store.py	Keyring-based secrets manager
src/scheduler.py	APScheduler cron jobs
src/heartbeat.py	Periodic health checks
src/memory_search.py	Ollama embeddings + SQLite semantic search
cli.py	CLI tool — status, doctor, logs, secrets, cron, etc.
setup.sh	Interactive 10-step setup wizard
bridge/whatsapp/	Node.js WhatsApp bridge (Baileys + Express)

CLI Usage

./cli.py status              # Bot online/offline, uptime
./cli.py doctor              # Full diagnostic check
./cli.py logs                # Tail echo-core.log
./cli.py restart             # Restart the service
./cli.py secrets list        # Show stored credentials
./cli.py cron list           # Show scheduled jobs
./cli.py whatsapp status     # WhatsApp bridge connection

Configuration

config.json — runtime configuration:

{
  "bot": {
    "name": "Echo",
    "default_model": "opus",
    "owner": "DISCORD_USER_ID",
    "admins": ["TELEGRAM_USER_ID"]
  },
  "channels": { },
  "telegram_channels": { },
  "whatsapp": {
    "enabled": true,
    "bridge_url": "http://127.0.0.1:8098",
    "owner": "PHONE_NUMBER"
  },
  "whatsapp_channels": { }
}

Secrets (Discord/Telegram tokens) are stored in the system keyring, not in config files.

Services

Echo Core runs as systemd user services:

systemctl --user start echo-core              # Start bot
systemctl --user start echo-whatsapp-bridge   # Start WA bridge
systemctl --user status echo-core             # Check status
journalctl --user -u echo-core -f             # Follow logs

Requirements

• Python 3.12+
• Claude Code CLI
• Node.js 22+ (only for WhatsApp bridge)

Tests

source .venv/bin/activate
pytest tests/

440 tests, zero failures.