# 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

```bash
# 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

```bash
# 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

```bash
./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:

```json
{
  "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:

```bash
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

```bash
source .venv/bin/activate
pytest tests/
```

440 tests, zero failures.