seedprod · UncleTallest · Mar 15, 2026 · Mar 15, 2026
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@ A personal AI assistant you can message from anywhere via Telegram.
 
 ## What is this?
 
-You know how Claude Code runs in your terminal and can read files, run commands, search the web, etc? This lets you talk to it from your phone via Telegram instead of being tied to your computer.
+Claude Code runs in your terminal with full tool access -- it can read files, run commands, search the web, spawn tasks, and more. This bot lets you talk to it from your phone via Telegram instead of being tied to your computer.
 
 **Text your bot → it runs Claude Code → sends back the response.**
 
@@ -13,18 +13,33 @@ Some things you can do:
 - "Search the web for the latest news on X"
 - "Read my notes and summarize them"
 - "Send me a daily briefing every morning at 7am"
+- "Run the tests and tell me if anything broke"
+- "What did I work on yesterday?" (with Continuity Bridge)
 
-It also works the other way - Claude can message YOU via Telegram (notifications when tasks finish, scheduled briefings, alerts, etc).
+It also works the other way -- Claude can message **you** via Telegram. Notifications when tasks finish, scheduled briefings, alerts, whatever you wire up.
 
-**The key is skills.** Out of the box, Claude Code can read files and search the web. But to make it truly YOUR assistant, create skills that give it access to your stuff:
-- Google Calendar (read your schedule)
-- Gmail (read-only access to emails)
-- Notes app (Obsidian, Apple Notes, etc.)
+**The key is skills.** Out of the box Claude Code can read files and search the web. But to make it truly your assistant, create skills that give it access to your stuff:
+- Google Calendar
+- Gmail
+- Notes (Obsidian, etc.)
 - Weather for your location
-- Whatever else you want
+- Your Continuity Bridge context
 
 The `skills/` folder has examples to get you started.
 
+---
+
+## Platform Support
+
+| Platform | Bot | Voice | Service manager |
+|----------|-----|-------|----------------|
+| macOS (Apple Silicon) | ✅ | ✅ mlx-whisper | launchd |
+| Linux | ✅ | ✅ faster-whisper | systemd |
+| macOS (Intel) | ✅ | ❌ | launchd |
+| Windows | Untested | Untested | — |
+
+---
+
 ## Quick Start
 
 Open Claude Code and paste:
@@ -40,124 +55,160 @@ Claude will walk you through:
 2. Getting your user ID from @userinfobot
 3. Configuring the `.env` file
 4. Installing the telegram-sender skill globally
-5. Setting up launchd to run the bot continuously
+5. Setting up your service manager (launchd on macOS, systemd on Linux)
 6. (Optional) Setting up scheduled skills like daily briefings
 
 ---
 
-## What's Included
-
-| File | Purpose |
-|------|---------|
-| `telegram-bot.py` | Receives messages from Telegram → sends to Claude Code |
-| `skills/telegram-sender/` | Lets Claude send messages TO you |
-| `skills/daily-brief/` | Example scheduled skill using telegram-sender |
-| `launchd/` | Templates for running bot + scheduled skills |
-
-## How It Works
-
-**Inbound (you → Claude):**
-```
-Telegram → telegram-bot.py → claude -p "message" → response → Telegram
-```
-
-**Outbound (Claude → you):**
-```
-Claude skill → telegram-sender/send.sh → Telegram API → you
-```
-
 ## Manual Setup
 
-If you prefer to set up manually instead of having Claude guide you:
-
 ### 1. Prerequisites
+
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
 - Python 3.10+
 
 ### 2. Create Telegram Bot
+
 1. Message [@BotFather](https://t.me/botfather) on Telegram
 2. Send `/newbot` and follow prompts
 3. Copy the bot token
 
 ### 3. Get Your User ID
+
 1. Message [@userinfobot](https://t.me/userinfobot) on Telegram
 2. Copy your user ID
 
 ### 4. Configure
+
 ```bash
 cp .env.example .env
 # Edit .env with your token and user ID
 ```
 
 ### 5. Install Dependencies
+
 ```bash
 pip install -r requirements.txt
 ```
 
+**Optional: Voice transcription**
+
+macOS (Apple Silicon):
+```bash
+pip install mlx-whisper
+```
+
+Linux:
+```bash
+pip install faster-whisper
+```
+
 ### 6. Install Skill Globally
+
 ```bash
 cp -r skills/telegram-sender ~/.claude/skills/
 ```
 
-### 7. Run Bot (Manual)
+### 7. Run the Bot
+
+**Manual (any platform):**
 ```bash
 python telegram-bot.py
 ```
 
-### 8. Run Bot (launchd - Recommended)
+**macOS — launchd (runs continuously, starts on login):**
 ```bash
 # Edit launchd/com.claude.telegram-bot.plist with your paths
 cp launchd/com.claude.telegram-bot.plist ~/Library/LaunchAgents/
 launchctl load ~/Library/LaunchAgents/com.claude.telegram-bot.plist
 ```
 
-## Bot Commands
-
-- `/new` - Clear session, start fresh
-- `/status` - Show session status
+**Linux — systemd (runs continuously, starts on login):**
+```bash
+# Edit paths in the service file
+sed -i 's/YOUR_USERNAME/'"$USER"'/g' systemd/claude-telegram-bot.service
 
-## Voice Messages (Apple Silicon)
+# Install and start
+mkdir -p ~/.config/systemd/user
+cp systemd/claude-telegram-bot.service ~/.config/systemd/user/
+systemctl --user daemon-reload
+systemctl --user enable --now claude-telegram-bot.service
 
-```bash
-pip install mlx-whisper
+# Check it's running
+systemctl --user status claude-telegram-bot.service
 ```
 
-Voice messages will be transcribed locally and sent to Claude.
+See `systemd/README.md` for full Linux service instructions.
+
+---
+
+## Bot Commands
+
+- `/new` — Clear session, start fresh
+- `/status` — Show session status and voice support
 
-## Example: Daily Briefing
+---
 
-The `skills/daily-brief/` shows how to create a scheduled skill that sends you a morning briefing via Telegram. See `skills/daily-brief/SKILL.md` for details.
+## Scheduling (Daily Briefings, etc.)
 
-To schedule it:
+**macOS — launchd:**
 ```bash
-# Edit launchd/com.claude.daily-brief.plist with your paths
+# Edit launchd/com.claude.daily-brief.plist with your paths and schedule
 cp launchd/com.claude.daily-brief.plist ~/Library/LaunchAgents/
 launchctl load ~/Library/LaunchAgents/com.claude.daily-brief.plist
 ```
 
+**Linux — systemd timer:**
+```bash
+sed -i 's/YOUR_USERNAME/'"$USER"'/g' systemd/claude-daily-brief.service
+cp systemd/claude-daily-brief.service ~/.config/systemd/user/
+cp systemd/claude-daily-brief.timer ~/.config/systemd/user/
+systemctl --user daemon-reload
+systemctl --user enable --now claude-daily-brief.timer
+
+# Verify timer is scheduled
+systemctl --user list-timers
+```
+
+Edit `systemd/claude-daily-brief.timer` to change the schedule. Default is 7:00 AM daily.
+
+---
+
+## What's Included
+
+| Path | Purpose |
+|------|---------|
+| `telegram-bot.py` | Main bot -- receives messages, runs Claude Code, sends response |
+| `skills/telegram-sender/` | Lets Claude send messages TO you |
+| `skills/daily-brief/` | Example scheduled skill using telegram-sender |
+| `launchd/` | macOS service templates |
+| `systemd/` | Linux service templates |
+
+---
+
 ## Security
 
 ### ALLOWED_USERS is critical
 
-**Always set `ALLOWED_USERS` in your `.env` file.** If left empty, anyone who discovers your bot's username can send it messages and run Claude with full tool access on your machine.
+**Always set `ALLOWED_USERS` in your `.env` file.** If left empty, anyone who discovers your bot's username can send it messages and run Claude Code with full tool access on your machine.
 
 ```bash
-# .env - always set this
+# .env — always set this
 ALLOWED_USERS=123456789
 ```
 
-Get your user ID from [@userinfobot](https://t.me/userinfobot) on Telegram.
+Get your user ID from [@userinfobot](https://t.me/userinfobot).
 
 ### Understand the tool access
 
 The bot runs Claude with these tools enabled:
-- `Read` / `Write` / `Edit` - file system access
-- `Bash` - shell command execution
-- `Glob` / `Grep` - file search
-- `WebFetch` / `WebSearch` - internet access
-- `Task` / `Skill` - agent spawning and skill execution
+- `Read` / `Write` / `Edit` — filesystem access
+- `Bash` — shell command execution
+- `Glob` / `Grep` — file search
+- `WebFetch` / `WebSearch` — internet access
+- `Task` / `Skill` — agent spawning and skill execution
 
-This is powerful and intentional for a personal assistant, but understand that messages you send can trigger real actions on your system.
+This is powerful and intentional for a personal assistant. Messages you send can trigger real actions on your system.
 
 ### Protect your tokens
 
@@ -167,12 +218,28 @@ This is powerful and intentional for a personal assistant, but understand that m
 
 ### Session file
 
-Sessions are stored in `~/.telegram-claude-sessions.json`. Default file permissions apply. On shared systems, consider restricting access:
+Sessions stored in `~/.telegram-claude-sessions.json`. On shared systems:
 
 ```bash
 chmod 600 ~/.telegram-claude-sessions.json
 ```
 
+---
+
+## Viewing Logs
+
+**macOS:**
+```bash
+tail -f /tmp/telegram-bot.log
+```
+
+**Linux (systemd):**
+```bash
+journalctl --user -u claude-telegram-bot.service -f
+```
+
+---
+
 ## License
 
 MIT
diff --git a/requirements.txt b/requirements.txt
@@ -1,4 +1,8 @@
 python-telegram-bot>=20.0
 mistune>=3.0
-# Optional: Voice transcription (Apple Silicon only)
+
+# Optional: Voice transcription (install one based on your platform)
+# macOS (Apple Silicon):
 # mlx-whisper
+# Linux:
+# faster-whisper