Ludext is a self-hosted assistant that runs on a Raspberry Pi. Every morning it collects your emails, calendar events, tasks, and news from your own infrastructure, builds a briefing, and sends you a Telegram message before you start your day.
No data ever leaves your home network. No subscriptions. No third-party APIs.
Most assistants send your personal data to external servers. Ludext is built around a different principle: your data stays yours.
- 🏠 Self-hosted data — Nextcloud stores your calendar, tasks, notes, photos, and news feeds on hardware you own and control.
- 🔒 Everything runs locally — even the semantic photo search uses a local CLIP model on the Pi; nothing is sent to any cloud provider.
- 💸 No subscriptions — Once set up, Ludext runs for free indefinitely.
| Layer | Technology | Role |
|---|---|---|
| Gmail (IMAP) | Fetches and filters unread messages | |
| Self-hosted data | Nextcloud | Calendar, tasks, news feeds, notes, photos |
| Photo search | CLIP (sentence-transformers) | Semantic photo search, runs locally |
| Delivery | Telegram Bot | Sends the briefing and accepts commands |
| Runtime | Raspberry Pi 4/5 | Runs the whole stack, 24/7 |
- 📧 Unread emails — filtered and summarized, only what matters
- 📅 Calendar — events for today and tomorrow
- ✅ Pending tasks — most urgent ones highlighted
- 📰 News — relevant articles from your Nextcloud News feeds
- 💊 Medicines — which ones to take today and at what time
Manage tasks, calendar events, medicines, shopping list, car expenses, and wishlist directly from Telegram. Search your Nextcloud photos by natural-language description (local CLIP model). The bot also monitors system health and sends automatic alerts for high CPU temperature, RAM, or disk usage.
→ Full command reference
→ Feature documentation
- Raspberry Pi 4 or 5 (8 GB RAM recommended)
- Calendar — for CalDAV events and tasks
- News — for RSS feed summaries
- Notes — for shopping list, car expenses, and medicine tracking
- A Gmail account with IMAP enabled
- A Telegram account to create a bot
nmapinstalled on the Pi (for the/redcommand)
git clone https://github.com/iamLudok/ludext.git ~/Ludext
cd ~/Ludextbash deploy/setup.shThis installs system dependencies, creates a Python virtual environment, installs the packages from requirements.txt, configures the daily cron job at 7:30, and installs the Telegram bot as a systemd service.
cp .env.example .env
nano .env| Variable | Description |
|---|---|
GMAIL_USER |
Your Gmail address |
GMAIL_APP_PASSWORD |
Gmail app password (see below) |
NEXTCLOUD_URL |
Your Nextcloud URL, e.g. http://192.168.1.50:8080 |
NEXTCLOUD_USER |
Your Nextcloud username |
NEXTCLOUD_PASSWORD |
Your Nextcloud password |
NEXTCLOUD_CALDAV_URL |
Usually NEXTCLOUD_URL/remote.php/dav |
TELEGRAM_TOKEN |
Your Telegram bot token |
TELEGRAM_CHAT_ID |
Your Telegram chat ID |
Gmail requires an app-specific password for IMAP access:
- Go to myaccount.google.com/security
- Enable 2-Step Verification if not already active
- Go to App passwords and create a new one named "Ludext"
- Copy the 16-character code into
.env→GMAIL_APP_PASSWORD
- Open Telegram and search for @BotFather
- Send
/newbotand follow the steps - Copy the token into
.env→TELEGRAM_TOKEN - Send any message to your new bot, then open:
https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates - Find
"id"inside"chat"— that's yourTELEGRAM_CHAT_ID
This makes Telegram show the command menu when you type / in the chat.
Run setMyCommands once with whichever commands you want to expose (replace <YOUR_TOKEN>):
curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/setMyCommands" \
-H "Content-Type: application/json" \
-d '{
"commands": [
{"command": "ayuda", "description": "Muestra todos los comandos"},
{"command": "tareas", "description": "Lista tus tareas pendientes"}
]
}'Full list of available commands: /ayuda inside the bot or docs/commands.md.
You only need to do this once — the commands persist on Telegram's side and survive bot restarts.
source ~/ludext-env/bin/activate
python3 ludext.pyUse --debug to save the generated briefing to a file:
python3 ludext.py --debug
cat ludext_briefing.txtLudext/
├── .env.example ← Template for .env
├── .gitignore ← Excludes files from git
├── LICENSE ← MIT license
├── ludext.py ← Daily briefing script (runs via cron)
├── README.md ← Project documentation
├── requirements.txt ← Python dependencies
├── bot/
│ ├── __main__.py ← Telegram polling and background threads
│ ├── background.py ← Background alerts
│ └── handlers.py ← Telegram bot command handlers
├── core/
│ ├── ai.py ← Builds the briefing text
│ ├── config.py ← Reads .env and exposes CONFIG
│ └── sources.py ← Data collection (emails, calendar, tasks, news)
├── deploy/
│ └── setup.sh ← Automated installation script
├── docs/
│ ├── commands.md ← Full Telegram command reference
│ └── features.md ← Feature documentation
├── notes/
│ ├── api.py ← Nextcloud Notes interface
│ ├── car.py ← Car expenses
│ ├── gf_gifts.py ← Gift ideas list
│ ├── medicine.py ← Medicine tracking
│ ├── shopping.py ← Shopping list
│ └── wishlist.py ← Wishlist
├── photos/
│ ├── indexer.py ← Indexes Nextcloud photos with CLIP
│ └── search.py ← Semantic photo search
├── scheduling/
│ ├── events.py ← Event CRUD (Nextcloud CalDAV)
│ └── tasks.py ← Task CRUD (Nextcloud CalDAV)
└── system/
├── monitor.py ← System monitor (CPU temp, RAM, disk, uptime)
└── network.py ← Network device scanner
crontab -l # daily briefing schedule
sudo systemctl status ludext-bot # Telegram bot service
cat ~/ludext.log # daily briefing logs
journalctl -u ludext-bot -n 50 --no-pager # bot logsMIT License — see LICENSE for details.