21d55cbc6a
setup.sh now installs eco → ~/.local/bin/eco (symlink to cli.py). README.md updated with full eco command reference. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
147 lines
4.8 KiB
Markdown
147 lines
4.8 KiB
Markdown
# 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
|
|
|
|
The setup wizard installs `eco` as a global command (`~/.local/bin/eco`):
|
|
|
|
```bash
|
|
eco status # Bot online/offline, uptime
|
|
eco doctor # Full diagnostic check
|
|
eco restart # Restart the service
|
|
eco restart --bridge # Restart bot + WhatsApp bridge
|
|
eco stop # Stop the service
|
|
eco logs # Tail echo-core.log (last 20 lines)
|
|
eco logs 50 # Last 50 lines
|
|
eco secrets list # Show stored credentials
|
|
eco secrets set <name> # Store a secret in keyring
|
|
eco secrets test # Check required secrets
|
|
eco sessions list # Active Claude sessions
|
|
eco sessions clear # Clear all sessions
|
|
eco channel list # Registered Discord channels
|
|
eco cron list # Show scheduled jobs
|
|
eco cron run <name> # Force-run a cron job
|
|
eco memory search "<query>" # Semantic search in memory
|
|
eco memory reindex # Rebuild search index
|
|
eco heartbeat # Run health checks
|
|
eco whatsapp status # WhatsApp bridge connection
|
|
eco whatsapp qr # QR code pairing instructions
|
|
eco send <alias> <message> # Send message via router
|
|
```
|
|
|
|
## 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.
|