diff --git a/README.md b/README.md index e783670..0a9d318 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# LettaBot 👾 +# LettaBot Your personal AI assistant that remembers everything across **Telegram, Slack, WhatsApp, and Signal**. Powered by [Letta Code](https://github.com/letta-ai/letta-code). @@ -11,7 +11,7 @@ Your personal AI assistant that remembers everything across **Telegram, Slack, W - **Persistent Memory** - Agent remembers conversations across sessions (days/weeks/months) - **Local Tool Execution** - Agent can read files, search code, run commands on your machine - **Heartbeat** - Periodic check-ins where the agent reviews tasks -- **Cron Jobs** - Agent can create its own scheduled tasks +- **Scheduling** - Agent can create one-off reminders and recurring tasks - **Streaming Responses** - Real-time message updates as the agent thinks ## Quick Start @@ -22,7 +22,7 @@ Your personal AI assistant that remembers everything across **Telegram, Slack, W - A Letta API key from [app.letta.com](https://app.letta.com) - A Telegram bot token from [@BotFather](https://t.me/BotFather) -### Install from Source +### Install ```bash # Clone the repository @@ -32,14 +32,12 @@ cd lettabot # Install dependencies npm install -# Build +# Build and link the CLI globally npm run build - -# Link the CLI globally (optional) npm link ``` -### Onboard +### Setup Run the interactive onboarding wizard: @@ -48,23 +46,16 @@ lettabot onboard ``` This will guide you through: -1. Setting up your Letta API key -2. Configuring Telegram (and optionally Slack) -3. Enabling heartbeat and cron jobs -4. Installing skills +1. Setting up your Letta API key (or OAuth login) +2. Configuring Telegram (and optionally Slack, WhatsApp, Signal) +3. Enabling heartbeat and scheduled tasks -### Run the Server +### Run ```bash lettabot server ``` -Or in development mode (auto-reload): - -```bash -npm run dev -``` - That's it! Message your bot on Telegram. ## CLI Commands @@ -74,8 +65,8 @@ That's it! Message your bot on Telegram. | `lettabot onboard` | Interactive setup wizard | | `lettabot server` | Start the bot server | | `lettabot configure` | View and edit configuration | -| `lettabot skills` | Configure which skills are enabled | -| `lettabot skills status` | Show skills status | +| `lettabot skills status` | Show enabled and available skills | +| `lettabot destroy` | Delete all local data and start fresh | | `lettabot help` | Show help | ## Multi-Channel Architecture @@ -107,7 +98,7 @@ At least one channel is required. Telegram is the easiest to start with. ## Configuration -### Basic (.env) +### Environment Variables (.env) ```bash # Required: Letta API Key @@ -115,6 +106,7 @@ LETTA_API_KEY=your_letta_api_key # Telegram (easiest to start) TELEGRAM_BOT_TOKEN=your_telegram_bot_token +TELEGRAM_DM_POLICY=pairing # pairing, allowlist, or open # Slack (optional) SLACK_BOT_TOKEN=xoxb-your-bot-token @@ -126,12 +118,11 @@ WHATSAPP_ENABLED=true # Signal (optional) SIGNAL_PHONE_NUMBER=+1XXXXXXXXXX -# Cron jobs (optional) +# Scheduling (optional) CRON_ENABLED=true # Heartbeat - periodic check-ins (optional) HEARTBEAT_INTERVAL_MIN=30 -# HEARTBEAT_TARGET=telegram:123456789 # defaults to last messaged ``` ### Full Configuration Reference @@ -140,16 +131,12 @@ HEARTBEAT_INTERVAL_MIN=30 |----------|----------|-------------| | `LETTA_API_KEY` | Yes | API key from app.letta.com | | `TELEGRAM_BOT_TOKEN` | * | Bot token from @BotFather | +| `TELEGRAM_DM_POLICY` | No | pairing/allowlist/open (default: pairing) | | `TELEGRAM_ALLOWED_USERS` | No | Comma-separated Telegram user IDs | | `SLACK_BOT_TOKEN` | * | Slack bot token (xoxb-...) | | `SLACK_APP_TOKEN` | * | Slack app token (xapp-...) | -| `SLACK_ALLOWED_USERS` | No | Comma-separated Slack user IDs | | `WHATSAPP_ENABLED` | No | Set to `true` to enable WhatsApp | -| `WHATSAPP_SESSION_PATH` | No | Path to store WhatsApp session | -| `WHATSAPP_ALLOWED_USERS` | No | Comma-separated phone numbers (+1...) | | `SIGNAL_PHONE_NUMBER` | * | Phone number registered with signal-cli | -| `SIGNAL_CLI_PATH` | No | Path to signal-cli binary | -| `SIGNAL_DM_POLICY` | No | pairing/allowlist/open (default: pairing) | | `WORKING_DIR` | No | Agent workspace (default: `/tmp/lettabot`) | | `CRON_ENABLED` | No | Enable scheduled tasks | | `HEARTBEAT_INTERVAL_MIN` | No | Heartbeat interval in minutes (e.g., `30`) | @@ -157,150 +144,97 @@ HEARTBEAT_INTERVAL_MIN=30 \* At least one channel must be configured -## Commands +## Bot Commands | Command | Description | |---------|-------------| | `/start` | Welcome message and help | -| `/new` | New conversation (keeps agent memory) | -| `/reset` | Fresh agent (clears all memory) | | `/status` | Show current session info | -| `/skills` | List installed skills | +| `/heartbeat` | Manually trigger a heartbeat check-in | ## Skills -LettaBot comes with 40+ builtin skills and supports installing more from [ClawdHub](https://clawdhub.com). +LettaBot supports skills that extend the agent's capabilities. -### Builtin Skills - -Skills are copied to `{WORKING_DIR}/.skills/` on server startup (where Letta Code discovers them): - -| Category | Skills | -|----------|--------| -| **Productivity** | 1password, apple-notes, apple-reminders, bear-notes, notion, obsidian, things-mac, trello | -| **Communication** | bird (Twitter), himalaya (email), imsg (iMessage), wacli (WhatsApp) | -| **Google** | google (Gmail, Calendar, Drive, Sheets, Docs), goplaces | -| **Media** | camsnap, gifgrep, nano-pdf, openai-image-gen, openai-whisper, summarize, video-frames | -| **Smart Home** | blucli, eightctl, openhue, sonoscli, spotify-player | -| **Dev Tools** | gemini, github, mcporter, oracle, peekaboo, tmux | -| **Utilities** | blogwatcher, cron, weather | - -### Install from ClawdHub +### View Skills ```bash -# Search for skills -npm run skill:search weather - -# Install a skill -npm run skill:install gog # Google Workspace (Gmail, Calendar, Drive) -npm run skill:install bird # Twitter/X -npm run skill:install obsidian # Obsidian notes -npm run skill:install sonoscli # Sonos speakers - -# List installed skills -npm run skill:list +lettabot skills status ``` -Browse all skills: https://clawdhub.com +Shows enabled skills and skills available to import: + +``` +Enabled (3): + ✓ gog + ✓ google + ✓ scheduling + +Available to import (20): + obsidian + weather + ... +``` + +### Feature-Gated Skills + +Some skills are automatically enabled based on your configuration: + +| Feature | Config | Skills Enabled | +|---------|--------|----------------| +| Scheduling | `CRON_ENABLED=true` | `scheduling` | +| Gmail | `GMAIL_ACCOUNT=...` | `gog`, `google` | ### Install from skills.sh -LettaBot is also compatible with [skills.sh](https://skills.sh) - the open agent skills ecosystem with 29K+ installs. +LettaBot is compatible with [skills.sh](https://skills.sh): ```bash # Interactive search npm run skills:find -# Install popular skill packs -npm run skills:add vercel-labs/agent-skills # React/Next.js best practices -npm run skills:add anthropics/skills # Frontend design, docs, PDFs -npm run skills:add expo/skills # React Native/Expo -npm run skills:add supabase/agent-skills # Supabase/Postgres - -# Or use npx directly -npx skills add coreyhaines31/marketingskills --global --yes +# Install skill packs +npm run skills:add supabase/agent-skills +npm run skills:add anthropics/skills ``` -Browse all skills: https://skills.sh - -### Configuring Skills - -Skills installed via ClawdHub or skills.sh are not automatically available to LettaBot. You need to configure which skills to enable: - -```bash -lettabot skills -``` - -This shows an interactive checklist of all available skills (from ClawdHub, skills.sh, and builtin). Select which skills to enable for your agent - checked skills will be available, unchecked skills will be removed. - -**Workflow:** -1. Install skills via ClawdHub or skills.sh (see above) -2. Run `lettabot skills` to configure which ones to enable -3. Restart the server (or the agent will pick them up on next interaction) - -## Heartbeat & Cron Jobs +## Heartbeat & Scheduling ### Heartbeat -LettaBot can periodically check in with you, reviewing a `HEARTBEAT.md` file for tasks: +LettaBot can periodically check in with you: ```bash -# Enable heartbeat (every 30 minutes) HEARTBEAT_INTERVAL_MIN=30 - -# Optional: specify delivery target (defaults to last messaged chat) -HEARTBEAT_TARGET=telegram:123456789 ``` -How it works: -1. Every N minutes, the system reads `HEARTBEAT.md` and sends its contents to the agent -2. The agent reviews the tasks and decides what to do -3. If nothing to do → agent calls `ignore()` tool → **response not delivered to you** (no spam!) -4. If there's something to report → agent's response is delivered to your chat - -### The `ignore()` Tool - -The agent has an `ignore()` tool for skipping responses: - -```python -ignore(reason="Nothing to report") # Skips delivery -``` - -This is useful for: -- Heartbeat check-ins with nothing to report -- Messages not directed at the agent -- Any situation where no response is needed - -Setup the tool: -```bash -npm run tools:setup # Upserts ignore() tool to Letta API -``` - -Edit `HEARTBEAT.md` in your working directory to add tasks you want to be reminded about. - -### Cron Jobs - -The agent can create its own scheduled tasks: +**Silent Mode**: During heartbeats, the agent's text output is NOT automatically sent to you. If the agent wants to contact you, it uses the `lettabot-message` CLI: ```bash -# Enable cron service -CRON_ENABLED=true +lettabot-message send --text "Hey, just checking in!" ``` -The agent uses the `lettabot-cron` CLI to manage jobs: +This prevents spam - the agent only messages you when there's something worth saying. +### Scheduling + +When `CRON_ENABLED=true`, the agent can create scheduled tasks: + +**One-off reminders:** ```bash -# Create a daily morning briefing -lettabot-cron create -n "Morning" -s "0 8 * * *" -m "Good morning! What's on the agenda?" - -# List all jobs -lettabot-cron list - -# Delete a job -lettabot-cron delete +lettabot-schedule create \ + --name "Standup" \ + --at "2026-01-28T20:15:00Z" \ + --message "Time for standup!" ``` -Jobs are stored in `cron-jobs.json` and auto-reload when changed. Responses are delivered to the last messaged chat (or specify `--deliver telegram:123456789`). +**Recurring schedules:** +```bash +lettabot-schedule create \ + --name "Morning Briefing" \ + --schedule "0 8 * * *" \ + --message "Good morning! What's on today's agenda?" +``` ## Security @@ -313,64 +247,33 @@ Jobs are stored in `cron-jobs.json` and auto-reload when changed. Responses are | Telegram | Long-polling (outbound HTTP) | None | | Slack | Socket Mode (outbound WebSocket) | None | | WhatsApp | Outbound WebSocket via Baileys | None | -| Signal | Local daemon on 127.0.0.1 | None (localhost only) | - -This is safer than webhook-based architectures that require exposing a public HTTP server. +| Signal | Local daemon on 127.0.0.1 | None | ### Tool Execution -LettaBot can execute tools on your machine. By default, it's restricted to **read-only** operations: +By default, the agent is restricted to **read-only** operations: - `Read`, `Glob`, `Grep` - File exploration - `web_search` - Internet queries - `conversation_search` - Search past messages -### Restricting Access +### Access Control -Set allowed users per channel in `.env`: - -```bash -TELEGRAM_ALLOWED_USERS=123456789,987654321 -SLACK_ALLOWED_USERS=U01234567,U98765432 -WHATSAPP_ALLOWED_USERS=+15551234567 -SIGNAL_ALLOWED_USERS=+15551234567 -``` - -## Architecture - -``` -┌─────────────────────────────────────────────────────────────┐ -│ LettaBot Core │ -│ │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │ Telegram │ │ Slack │ │ WhatsApp │ │ Signal │ │ -│ │ (grammY) │ │ (Bolt) │ │ (Baileys)│ │(signal-cli)│ │ -│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ -│ └─────────────┼─────────────┼─────────────┘ │ -│ ▼ │ -│ ┌─────────────────┐ │ -│ │ Letta Agent │ ◄── Single agent, │ -│ │ (Memory) │ single conversation │ -│ └────────┬────────┘ │ -└───────────────────────┼─────────────────────────────────────┘ - ▼ - Letta Code SDK → CLI → Local Tools - │ - ▼ - Letta Server (Memory + LLM) -``` +LettaBot supports pairing-based access control. When `TELEGRAM_DM_POLICY=pairing`: +1. Unauthorized users get a pairing code +2. You approve codes via `lettabot pairing approve telegram ` +3. Approved users can then chat with the bot ## Development ```bash -# Run in development mode (uses Letta Cloud) +# Run in development mode (auto-reload) npm run dev # Build for production npm run build -npm start -# Run setup wizard -npm run setup +# Start production server +lettabot server ``` ### Local Letta Server @@ -378,72 +281,45 @@ npm run setup To use a local Letta server instead of Letta Cloud: ```bash -# Point to local server -LETTA_BASE_URL=http://localhost:8283 npm run dev - -# With a specific agent ID (useful if agent already exists) -LETTA_BASE_URL=http://localhost:8283 LETTA_AGENT_ID=agent-xxx npm run dev +LETTA_BASE_URL=http://localhost:8283 lettabot server ``` -The `LETTA_AGENT_ID` env var overrides the stored agent ID, useful for testing with different agents or servers. - ## Troubleshooting ### WhatsApp **Session errors / "Bad MAC" messages** -These are normal Signal Protocol renegotiation messages. They're noisy but harmless - WhatsApp will still work. +These are normal Signal Protocol renegotiation messages. They're noisy but harmless. **Messages going to wrong chat** -If using selfChatMode and messages go to the wrong place, clear the session and re-link: +Clear the session and re-link: ```bash rm -rf ./data/whatsapp-session -npm run dev # Scan QR again -``` - -**Competing with another WhatsApp client** -If you have clawdbot/moltbot running, it will compete for WhatsApp. Stop it first: -```bash -launchctl unload ~/Library/LaunchAgents/com.clawdbot.gateway.plist +lettabot server # Scan QR again ``` ### Signal **Port 8090 already in use** -Change the port in `.env`: ```bash SIGNAL_HTTP_PORT=8091 ``` -**Daemon won't start** -Make sure signal-cli is in your PATH or set the full path: -```bash -SIGNAL_CLI_PATH=/opt/homebrew/bin/signal-cli -``` - ### General **Agent not responding** -Check if the agent ID is correct in `lettabot-agent.json`. If corrupted, delete it to create a fresh agent: +Delete the agent store to create a fresh agent: ```bash rm lettabot-agent.json -npm run dev +lettabot server ``` -**Messages queuing up / slow responses** -Messages are processed one at a time to prevent SDK issues. If many messages arrive at once, they'll queue. - ## Documentation +- [Getting Started](docs/getting-started.md) - [Slack Setup](docs/slack-setup.md) - [WhatsApp Setup](docs/whatsapp-setup.md) - [Signal Setup](docs/signal-setup.md) -- [Architecture](ARCHITECTURE.md) -- [Implementation Plan](PLAN.md) - -## Acknowledgments - -Some builtin skills are adapted from [ClawdBot](https://github.com/anthropics/clawdbot) (MIT License, Copyright © 2025 Peter Steinberger). ## License diff --git a/image (1).png b/image (1).png deleted file mode 100644 index ac1e588..0000000 Binary files a/image (1).png and /dev/null differ diff --git a/image.png b/image.png deleted file mode 100644 index 33f9187..0000000 Binary files a/image.png and /dev/null differ