lettabot
Set up and run LettaBot - a multi-channel AI assistant for Telegram, Slack, Discord, WhatsApp, and Signal. Supports both interactive wizard and non-interactive (agent-friendly) configuration.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/letta-ai/lettabot with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/letta-ai/lettabot'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/letta-ai--lettabot)HTML
<a href="/listings/letta-ai--lettabot"><img src="/api/listings/letta-ai--lettabot/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Prerequisites
- Node.js 20+ - A Letta API key from [app.letta.com](https://app.letta.com) (or a running [Letta Docker server](https://docs.letta.com/guides/docker/)) - A Telegram bot token from [@BotFather](https://t.me/BotFather) - Optional: a ChatGPT subscription account you want to use for model credits
Install
# Clone the repository git clone https://github.com/letta-ai/lettabot.git cd lettabot # Install dependencies npm install # Build and link the CLI globally npm run build npm link
Update
# Pull latest changes git pull origin main # Reinstall dependencies and rebuild npm install npm run build
Optional: Run a Letta Docker server
You can use `lettabot` with a Docker server with:
docker run \ -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \ -p 8283:8283 \ -e OPENAI_API_KEY="your_openai_api_key" \ letta/letta:latest
See the [documentation](https://docs.letta.com/guides/docker/) for more details on running with Docker.
Setup
**Option 1: AI-Assisted Setup (Recommended)**
Paste this into Letta Code, Claude Code, Cursor, or any AI coding assistant:
Clone https://github.com/letta-ai/lettabot, read the SKILL.md for setup instructions, and help me configure Telegram.
You'll need: - A Letta API key from [app.letta.com](https://app.letta.com) (or a [Letta Docker server](https://docs.letta.com/guides/docker/)) - A Telegram bot token from [@BotFather](https://t.me/BotFather)
The AI will handle cloning, installing, and configuration autonomously.
**Option 2: Interactive Wizard**
For manual step-by-step setup:
git clone https://github.com/letta-ai/lettabot.git cd lettabot npm install && npm run build && npm link lettabot onboard
Prefer to use your ChatGPT subscription instead of another API key? After onboarding (or anytime), run:
lettabot connect chatgpt
This opens a browser flow and enables connected subscription handles in the model picker.
Run
lettabot server
That's it! Message your bot on Telegram.
> **Note:** For detailed environment variable reference and multi-channel setup, see [SKILL.md](./SKILL.md)
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 404 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: lettabot
- description: Set up and run LettaBot - a multi-channel AI assistant for Telegram, Slack, Discord, WhatsApp, and Signal. Supports both interactive wizard and non-interactive (agent-friendly) configuration.
- ---
- # LettaBot Setup
- Multi-channel AI assistant with persistent memory across Telegram, Slack, Discord, WhatsApp, and Signal.
- ## Quick Setup (Agent-Friendly)
- For non-interactive setup (ideal for coding agents):
- ```bash
- # 1. Clone and install
- git clone https://github.com/letta-ai/lettabot.git
- cd lettabot
- npm install
- npm run build
- npm link
- # 2. Configure required variables
- export LETTA_API_KEY="letta_..." # From app.letta.com
- # 3. Configure channel (example: Telegram)
- export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..." # From @BotFather
- # 4. Run non-interactive setup
- lettabot onboard --non-interactive
- # 5. Start the bot
- lettabot server
- ```
- **Safe defaults used if not set:**
- - `LETTA_BASE_URL`: `https://api.letta.com`
- - `LETTA_AGENT_NAME`: `"lettabot"`
- - Model: selected during `lettabot onboard` or changed with `lettabot model set <handle>`
- - `*_DM_POLICY`: `"pairing"` (requires approval before messaging)
- - `WHATSAPP_SELF_CHAT_MODE`: `true` (only "Message Yourself" chat)
- - `SIGNAL_SELF_CHAT_MODE`: `true` (only "Note to Self")
- The setup will show which defaults are being used and validate safety-critical settings.
- ## Interactive Setup
- For human-friendly setup with wizard:
- ```bash
- lettabot onboard
- ```
- The wizard will guide you through:
- - Letta API authentication (OAuth or API key)
- - Agent selection/creation
- - Channel configuration (Telegram, Slack, Discord, WhatsApp, Signal)
- ## Environment Variables
- ### Authentication
- | Variable | Description | Default |
- |----------|-------------|---------|
- | `LETTA_API_KEY` | API key from app.letta.com | Required (unless using a Docker server) |
- | `LETTA_BASE_URL` | API endpoint | `https://api.letta.com` |
- ### Agent Selection
- | Variable | Description | Default |
- |----------|-------------|---------|
- | `LETTA_AGENT_ID` | Use existing agent (skip agent creation) | Creates new agent |
- | `LETTA_AGENT_NAME` | Name for new agent | `"lettabot"` |
- | ~~`LETTA_MODEL`~~ | *Removed* - model is set on the agent server-side. Use `lettabot model set <handle>`. | - |
- ### Telegram
- | Variable | Description | Required | Default |
- |----------|-------------|----------|---------|
- | `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather | ✅ | - |
- | `TELEGRAM_DM_POLICY` | Access control: `pairing` \| `allowlist` \| `open` | ❌ | `pairing` |
- | `TELEGRAM_ALLOWED_USERS` | Comma-separated user IDs (if dmPolicy=allowlist) | ❌ | - |
- ### Slack (Socket Mode)
- | Variable | Description | Required | Default |
- |----------|-------------|----------|---------|
- | `SLACK_BOT_TOKEN` | Bot User OAuth Token (xoxb-...) | ✅ | - |
- | `SLACK_APP_TOKEN` | App-Level Token (xapp-...) for Socket Mode | ✅ | - |
- | `SLACK_APP_NAME` | Custom app name | ❌ | `LETTA_AGENT_NAME` or `"LettaBot"` |
- | `SLACK_DM_POLICY` | Access control: `pairing` \| `allowlist` \| `open` | ❌ | `pairing` |
- | `SLACK_ALLOWED_USERS` | Comma-separated Slack user IDs (if dmPolicy=allowlist) | ❌ | - |
- **Setup Slack app:** See [Slack Setup Wizard](./src/setup/slack-wizard.ts) or run `lettabot onboard` for guided setup.
- ### Discord
- | Variable | Description | Required | Default |
- |----------|-------------|----------|---------|
- | `DISCORD_BOT_TOKEN` | Bot token from discord.com/developers/applications | ✅ | - |
- | `DISCORD_DM_POLICY` | Access control: `pairing` \| `allowlist` \| `open` | ❌ | `pairing` |
- | `DISCORD_ALLOWED_USERS` | Comma-separated Discord user IDs (if dmPolicy=allowlist) | ❌ | - |
- **Setup Discord bot:** See [docs/discord-setup.md](./docs/discord-setup.md)
- | Variable | Description | Required | Default |
- |----------|-------------|----------|---------|
- | `WHATSAPP_ENABLED` | Enable WhatsApp: `true` \| `false` | ✅ | - |
- | `WHATSAPP_SELF_CHAT_MODE` | Self-chat mode: `true` (personal) \| `false` (dedicated) | ✅ | `true` (safe) |
- | `WHATSAPP_DM_POLICY` | Access control: `pairing` \| `allowlist` \| `open` | ❌ | `pairing` |
- | `WHATSAPP_ALLOWED_USERS` | Comma-separated phone numbers with + (if dmPolicy=allowlist) | ❌ | - |
- **CRITICAL - Read Before Enabling:**
- - `WHATSAPP_SELF_CHAT_MODE=true` (personal number): Only responds to "Message Yourself" chat ✅ SAFE
- - `WHATSAPP_SELF_CHAT_MODE=false` (dedicated bot number): Responds to ALL incoming messages ⚠️ USE WITH CAUTION
- - Default is `true` for safety - bot will NOT message your contacts unless you explicitly set to `false`
- **First-Time Setup - QR Code Warning:**
- - QR code prints to console when `lettabot server` runs for the first time
- - **DO NOT background the server** until after QR code is scanned
- - **AI agents using Letta Code or similar**: Output may be truncated! If QR code is not visible:
- 1. Tell the agent to stop the server
- 2. Run `lettabot server` yourself in a terminal
- 3. Scan the QR code when it appears
- 4. After pairing, the agent can manage the server normally
- - Alternative: Instruct agent "Run lettabot server in FOREGROUND and do NOT background it"
- - After initial pairing completes, server can be backgrounded in future runs
- ### Signal
- | Variable | Description | Required | Default |
- |----------|-------------|----------|---------|
- | `SIGNAL_PHONE_NUMBER` | Your phone number (with +) | ✅ | - |
- | `SIGNAL_DM_POLICY` | Access control: `pairing` \| `allowlist` \| `open` | ❌ | `pairing` |
- | `SIGNAL_ALLOWED_USERS` | Comma-separated phone numbers with + (if dmPolicy=allowlist) | ❌ | - |
- **Setup:** Requires Signal CLI - see [signal-cli documentation](https://github.com/AsamK/signal-cli).
- ## Channel-Specific Setup
- ### Telegram Bot Setup
- 1. Message [@BotFather](https://t.me/BotFather) on Telegram
- 2. Send `/newbot` and follow prompts
- 3. Copy the token (format: `123456:ABC-DEF...`)
- 4. Set `TELEGRAM_BOT_TOKEN` environment variable
- ### Slack App Setup (Interactive)
- For Socket Mode (required for real-time messages):
- ```bash
- lettabot onboard
- # Select "Slack" → "Guided setup"
- ```
- This uses a manifest to pre-configure:
- - Socket Mode
- - 5 bot scopes (app_mentions:read, chat:write, im:*)
- - 2 event subscriptions (app_mention, message.im)
- ### Slack App Setup (Manual)
- 1. Go to [api.slack.com/apps](https://api.slack.com/apps)
- 2. Create app from manifest (see `src/setup/slack-wizard.ts` for manifest YAML)
- 3. Install to workspace → copy Bot Token (`xoxb-...`)
- 4. Enable Socket Mode → generate App Token (`xapp-...`)
- 5. Set both tokens in environment
- ## Access Control
- Each channel supports three DM policies:
- - **`pairing`** (recommended): Users get a code, you approve via CLI (`lettabot pairing approve <channel> <code>`) or API (`POST /api/v1/pairing/<channel>/approve`)
- - **`allowlist`**: Only specified user IDs can message
- - **`open`**: Anyone can message (not recommended)
- ## Conversation Routing
- By default, all channels share **one conversation**. You can switch to per-channel conversation histories.
- **Single-agent config (top-level):**
- ```yaml
- conversations:
- mode: shared # "shared" (default) or "per-channel"
- heartbeat: last-active # "dedicated" | "last-active" | "<channel>"
- ```
- **Multi-agent config (per agent):**
- ```yaml
- agents:
- - name: MyAgent
- conversations:
- mode: per-channel
- heartbeat: dedicated
- ```
- Notes:
- - `per-channel` means one conversation per **channel adapter** (telegram/slack/discord/etc), not per chat/user.
- - Agent memory remains shared across channels; only the conversation history is separated.
- - `heartbeat` controls which conversation background triggers use: a dedicated stream, the last active channel, or an explicit channel name.
- ## Group Settings (Optional)
- Group settings apply to Telegram, Slack, Discord, WhatsApp, and Signal.
- **YAML fields (per channel under `channels.<name>`):**
- - `groupDebounceSec`: Debounce seconds for group batching (default: 5)
- - `groups`: Map of group IDs to config (use `*` as the default)
- - `mode`: `open` | `listen` | `mention-only` | `disabled`
- - `allowedUsers`: Restrict who can trigger the bot in that group
- - `receiveBotMessages`: Allow bot/bot messages (default: false)
- - `mentionPatterns`: Extra regex patterns for mention detection (Telegram/WhatsApp/Signal)
- - `instantGroups`: Group IDs that bypass batching (**legacy**)
- - `groupPollIntervalMin`: Deprecated (minutes)
- - `listeningGroups`: Deprecated (use `groups.<id>.mode: listen`)
- **Environment variables (non-interactive onboarding):**
- Only legacy group options are supported here; prefer editing `lettabot.yaml` for `groups` config.
- - `<CHANNEL>_GROUP_DEBOUNCE_SEC` (seconds, e.g. `5`)
- - `<CHANNEL>_GROUP_POLL_INTERVAL_MIN` (deprecated, use `_GROUP_DEBOUNCE_SEC` instead)
- - `<CHANNEL>_INSTANT_GROUPS` (comma-separated, legacy)
- - `<CHANNEL>_LISTENING_GROUPS` (comma-separated, legacy)
- Example:
- ```yaml
- channels:
- slack:
- enabled: true
- botToken: xoxb-...
- appToken: xapp-...
- groupDebounceSec: 5
- mentionPatterns: ["@mybot", "hey bot"]
- groups:
- "*": { mode: mention-only }
- "C0987654321": { mode: listen }
- "C0123456789": { mode: open, allowedUsers: ["U123"] }
- ```
- ## Configuration File
- After onboarding, config is saved to `~/.lettabot/config.yaml`:
- ```yaml
- server:
- baseUrl: https://api.letta.com
- apiKey: letta_...
- agentId: agent-...
- conversations:
- mode: shared
- heartbeat: last-active
- channels:
- telegram:
- enabled: true
- botToken: 123456:ABC-DEF...
- dmPolicy: pairing
- slack:
- enabled: true
- botToken: xoxb-...
- appToken: xapp-...
- dmPolicy: pairing
- ```
- Edit this file directly or re-run `lettabot onboard` to reconfigure.
- ## Commands
- ```bash
- # Setup
- lettabot onboard # Interactive wizard
- lettabot onboard --non-interactive # Env-based setup (agent-friendly)
- # Run
- lettabot server # Start bot server
- # Manage
- lettabot pairing list # List pending pairing requests
- lettabot pairing approve <channel> <code> # Approve user
- lettabot skills # Enable/disable skills
- # Scheduling
- lettabot cron list # List scheduled tasks
- lettabot cron add "Daily standup at 9am" "0 9 * * *" # Add cron job
- ```
- ## Troubleshooting
- ### "Module not found" errors
- Make sure you've run `npm run build` after installing or pulling updates.
- ### Telegram bot not responding
- 1. Check token is correct: `curl https://api.telegram.org/bot<TOKEN>/getMe`
- 2. Ensure bot is started: `lettabot server` should show "Connected to Telegram"
- 3. Check access control: User may need pairing approval
- ### Slack not receiving messages
- 1. Verify Socket Mode is enabled in Slack app settings
- 2. Check both tokens are set: `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`
- 3. Ensure event subscriptions are configured (app_mention, message.im)
- ### WhatsApp QR code not appearing
- 1. Make sure Signal Desktop is closed (conflicts with baileys)
- 2. Delete `~/.wwebjs_auth` if previously used different library
- 3. Check no other WhatsApp Web sessions are active
- ## Example: Agent Setup Flow
- For coding agents helping users set up LettaBot:
- ```bash
- # 1. Clone and build
- git clone https://github.com/letta-ai/lettabot.git
- cd lettabot
- npm install && npm run build && npm link
- # 2. Get Letta API key
- # Guide user to app.letta.com → API Keys → Create Key
- # 3. Get Telegram bot token
- # Guide user to @BotFather → /newbot → follow prompts
- # 4. Set environment variables
- export LETTA_API_KEY="letta_..."
- export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
- # Defaults will be used for LETTA_BASE_URL, agent name, and DM policy
- # 5. Run non-interactive setup
- lettabot onboard --non-interactive
- # 6. Instruct user to start server
- # DON'T start server automatically - user must see output
- echo "Setup complete! Run 'lettabot server' to start the bot."
- ```
- **For WhatsApp (QR code required on first run):**
- ```bash
- export LETTA_API_KEY="letta_..."
- export WHATSAPP_ENABLED="true"
- export WHATSAPP_SELF_CHAT_MODE="true" # REQUIRED: true=personal number, false=dedicated bot
- lettabot onboard --non-interactive
- # CRITICAL: Do NOT auto-start the server!
- # Tell user: "WhatsApp setup complete. Please run 'lettabot server' in your terminal."
- # User must see QR code in console output to scan it.
- # After first pairing, server can be managed normally.
- ```
- **Agent Instructions:**
- If an AI agent is helping with setup and WhatsApp is configured:
- 1. Complete `lettabot onboard --non-interactive`
- 2. **DO NOT** run `lettabot server` automatically
- 3. Tell user: "Setup complete! Please run `lettabot server` in a terminal to see the WhatsApp QR code"
- 4. Wait for user confirmation that QR was scanned
- 5. After confirmation, server can be managed normally
- The agent can verify success by checking:
- - `lettabot server` output shows "Connected to Telegram" (or other channel)
- - Config file exists at `~/.lettabot/config.yaml`
- - User can message bot on configured channel(s)
- ## Docker Server Letta
- To use a Letta Docker server:
- ```bash
- # Run Letta Docker
- docker run -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
- -p 8283:8283 \
- -e OPENAI_API_KEY="your_openai_api_key" \
- letta/letta:latest
- # Configure LettaBot
- export LETTA_BASE_URL="http://localhost:8283"
- export LETTA_API_KEY="sk-..." # From Letta admin panel
- lettabot onboard --non-interactive
- ```
- ## Skills Integration
- LettaBot supports loading skills from:
- - **Clawdhub** ([clawdhub.com](https://clawdhub.com))
- - **skills.sh** repositories
- - Local `.skills/` directory
- ```bash
- # Install skill from Clawdhub
- npx molthub@latest install sonoscli
- # Connect to LettaBot
- lettabot skills
- # Space to toggle, Enter to confirm
- # Skills will be available to agent
- ```
README.md · README · 474 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <div align="center">
- # LettaBot is deprecated
- </div>
- > [!WARNING]
- > **LettaBot is no longer actively maintained.** All new development is happening in [Letta Code](https://docs.letta.com/letta-code) via [Channels](https://docs.letta.com/letta-code/channels) and [Remote Environments](https://docs.letta.com/letta-code/remote).
- >
- > **Where to go instead:**
- > - **Telegram / Slack messaging** → [Channels](https://docs.letta.com/letta-code/channels) — same agent, same memory, integrated into Letta Code directly
- > - **Always-on agent on a VPS or server** → [Remote Environments](https://docs.letta.com/letta-code/remote) — `letta server` uses outbound WebSocket, no ports to open, no reverse proxy needed
- > - **Heartbeats and scheduled tasks** → [letta cron](https://docs.letta.com/letta-code/scheduling) — built into remote environments
- >
- > Existing LettaBot deployments will continue to function, but for any new project, use Channels + Remote Environments. Migration is typically straightforward (~20 minutes).
- >
- > **Need migration help?** Ask in the `#ezra` channel on the [Letta Discord](https://discord.gg/letta).
- ---
- # LettaBot
- Your personal AI assistant that remembers everything across **Telegram, Slack, Discord, WhatsApp, and Signal** — plus Bluesky Jetstream feed ingestion. Powered by the [Letta Code SDK](https://github.com/letta-ai/letta-code-sdk).
- <img width="750" alt="lettabot-preview" src="assets/preview.jpg" />
- [](https://railway.com/deploy/lettabot?utm_medium=integration&utm_source=template&utm_campaign=generic)
- [](https://discord.gg/letta)
- > [!IMPORTANT]
- > *"Help! I need help with my LettaBot!"* 👋
- >
- > Need help? The fastest way to get help with LettaBot is to ask an AI coding agent, like [Letta Code](https://docs.letta.com/letta-code)! The LettaBot codebase is meant to be hackable, meaning a (good) agent should be able to dive right in and help you out.
- ## Features
- - **Multi-Channel** - Chat seamlessly across Telegram, Slack, Discord, WhatsApp, and Signal
- - **Feed Ingestion** - Read-only Bluesky Jetstream stream for selected DID(s)
- - **Unified Memory** - Single agent remembers everything from all channels
- - **Persistent Memory** - Agent remembers conversations across sessions (days/weeks/months)
- - **Local Tool Execution** - Agent can read files, search code, run commands on your machine
- - **Voice Messages** - Automatic transcription via OpenAI Whisper
- - **Heartbeat** - Periodic check-ins where the agent reviews tasks
- - **Scheduling** - Agent can create one-off reminders and recurring tasks
- - **Streaming Responses** - Real-time message updates as the agent thinks
- ## Quick Start
- ### Prerequisites
- - Node.js 20+
- - A Letta API key from [app.letta.com](https://app.letta.com) (or a running [Letta Docker server](https://docs.letta.com/guides/docker/))
- - A Telegram bot token from [@BotFather](https://t.me/BotFather)
- - Optional: a ChatGPT subscription account you want to use for model credits
- ### Install
- ```bash
- # Clone the repository
- git clone https://github.com/letta-ai/lettabot.git
- cd lettabot
- # Install dependencies
- npm install
- # Build and link the CLI globally
- npm run build
- npm link
- ```
- ### Update
- ```bash
- # Pull latest changes
- git pull origin main
- # Reinstall dependencies and rebuild
- npm install
- npm run build
- ```
- #### Optional: Run a Letta Docker server
- You can use `lettabot` with a Docker server with:
- ```
- docker run \
- -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
- -p 8283:8283 \
- -e OPENAI_API_KEY="your_openai_api_key" \
- letta/letta:latest
- ```
- See the [documentation](https://docs.letta.com/guides/docker/) for more details on running with Docker.
- ### Setup
- **Option 1: AI-Assisted Setup (Recommended)**
- Paste this into Letta Code, Claude Code, Cursor, or any AI coding assistant:
- ```
- Clone https://github.com/letta-ai/lettabot, read the SKILL.md
- for setup instructions, and help me configure Telegram.
- ```
- You'll need:
- - A Letta API key from [app.letta.com](https://app.letta.com) (or a [Letta Docker server](https://docs.letta.com/guides/docker/))
- - A Telegram bot token from [@BotFather](https://t.me/BotFather)
- The AI will handle cloning, installing, and configuration autonomously.
- **Option 2: Interactive Wizard**
- For manual step-by-step setup:
- ```bash
- git clone https://github.com/letta-ai/lettabot.git
- cd lettabot
- npm install && npm run build && npm link
- lettabot onboard
- ```
- Prefer to use your ChatGPT subscription instead of another API key? After onboarding (or anytime), run:
- ```bash
- lettabot connect chatgpt
- ```
- This opens a browser flow and enables connected subscription handles in the model picker.
- ### Run
- ```bash
- lettabot server
- ```
- That's it! Message your bot on Telegram.
- > **Note:** For detailed environment variable reference and multi-channel setup, see [SKILL.md](./SKILL.md)
- ## Voice
- LettaBot can transcribe incoming voice messages (via OpenAI Whisper or Mistral Voxtral) and reply with voice memos (via ElevenLabs or OpenAI TTS). Voice notes render as native bubbles on Telegram and WhatsApp.
- **Supported channels:** Telegram, WhatsApp, Signal, Slack, Discord
- See [docs/voice.md](./docs/voice.md) for full setup, configuration, and troubleshooting.
- ## Skills
- LettaBot is compatible with [skills.sh](https://skills.sh) and [Clawdhub](https://clawdhub.com/).
- ```bash
- # from Clawdhub
- npx molthub@latest install sonoscli
- # from skills.sh
- npm run skills:add supabase/agent-skills
- # connect to LettaBot
- lettabot skills
- ◆ Enable skills (space=toggle, enter=confirm):
- │ ◻ ── ClawdHub Skills ── (~/clawd/skills)
- │ ◻ 🦞 sonoscli
- │ ◻ ── Vercel Skills ── (~/.agents/skills)
- │ ◻ 🔼 supabase/agent-skills
- │ ◻ ── Built-in Skills ──
- │ ◻ 📦 1password
- │ ◻ ...
- # View LettaBot skills
- lettabot skills status
- ```
- ### Home Assistant
- Control your smart home with LettaBot:
- ```bash
- # 1. Install the skill from ClawdHub
- npx clawdhub@latest install homeassistant
- # 2. Enable the skill
- lettabot skills sync
- # Select "homeassistant" from the list
- # 3. Configure credentials (see skill docs for details)
- # You'll need: HA URL + Long-Lived Access Token
- ```
- Then ask your bot things like:
- - "Turn off the living room lights"
- - "What's the temperature in the bedroom?"
- - "Set the thermostat to 72"
- ## CLI Commands
- | Command | Description |
- |---------|-------------|
- | `lettabot onboard` | Interactive setup wizard |
- | `lettabot connect` | Connect model providers (for example, `chatgpt`) |
- | `lettabot server` | Start the bot server |
- | `lettabot configure` | View and edit configuration |
- | `lettabot skills status` | Show enabled and available skills |
- | `lettabot destroy` | Delete all local data and start fresh |
- | `lettabot help` | Show help |
- ## Channel Setup
- By default, LettaBot uses a **single agent with a single shared conversation** across all channels:
- ```
- Telegram ──┐
- Slack ─────┤
- Discord ───┼──→ ONE AGENT ──→ ONE CONVERSATION
- WhatsApp ──┤ (memory) (chat history)
- Signal ────┘
- ```
- - Start a conversation on Telegram
- - Continue it on Slack
- - Pick it up on WhatsApp
- - The agent remembers everything!
- You can also enable **per-channel conversations** (one conversation per channel adapter, not per chat/user):
- ```
- Telegram ──→ CONVERSATION (telegram)
- Slack ─────→ CONVERSATION (slack)
- Discord ───→ CONVERSATION (discord)
- WhatsApp ──→ CONVERSATION (whatsapp)
- Signal ────→ CONVERSATION (signal)
- (shared agent memory across channels)
- ```
- Configure in `lettabot.yaml`:
- ```yaml
- conversations:
- mode: shared # default: one conversation across all channels
- heartbeat: last-active # "dedicated" | "last-active" | "<channel>"
- ```
- For multi-agent configs, the same block lives under each agent:
- ```yaml
- agents:
- - name: MyAgent
- conversations:
- mode: per-channel
- heartbeat: dedicated
- ```
- | Channel | Guide | Requirements |
- |---------|-------|--------------|
- | Telegram | [Setup Guide](docs/getting-started.md) | Bot token from @BotFather |
- | Slack | [Setup Guide](docs/slack-setup.md) | Slack app with Socket Mode |
- | Discord | [Setup Guide](docs/discord-setup.md) | Discord bot + Message Content Intent |
- | WhatsApp | [Setup Guide](docs/whatsapp-setup.md) | Phone with WhatsApp |
- | Signal | [Setup Guide](docs/signal-setup.md) | signal-cli + phone number |
- | Bluesky (read-only) | [Setup Guide](docs/bluesky-setup.md) | Jetstream WebSocket + DID filter |
- At least one channel is required. Telegram is the easiest to start with.
- ### Group Settings (Optional)
- Configure group batching and per-group response modes in `lettabot.yaml`:
- ```yaml
- channels:
- slack:
- groupDebounceSec: 5
- mentionPatterns: ["@mybot", "hey bot"]
- groups:
- "*": { mode: mention-only } # default for all groups
- "C0987654321": { mode: listen } # observe, only reply on mention
- "C0123456789": { mode: open, allowedUsers: ["U123"] }
- ```
- Group modes:
- - `open`: process + respond to all group messages
- - `listen`: process for memory, but auto-replies only on mention
- - `mention-only`: only process when mentioned
- - `disabled`: ignore all group messages
- Notes:
- - `instantGroups` still bypasses batching (legacy).
- - `listeningGroups` and `groups.<id>.requireMention` are deprecated; use `groups.<id>.mode`.
- See `SKILL.md` for the full environment variable list and examples.
- ## Bot Commands
- | Command | Description |
- |---------|-------------|
- | `/start` | Welcome message and help |
- | `/status` | Show current session info |
- | `/heartbeat` | Manually trigger a heartbeat check-in |
- ## Background Tasks (Heartbeats & Cron)
- Heartbeats always run in **Silent Mode**. Cron jobs are **silent by default**, but can auto-deliver responses when created with `--deliver channel:chatId`.
- Silent Mode means the agent's text responses are NOT automatically sent to users during background tasks. This is intentional: the agent decides when something is worth interrupting you for.
- To send messages during silent mode, the agent must explicitly use the CLI:
- ```bash
- lettabot-message send --text "Hey, I found something interesting!"
- ```
- The agent sees a clear `[SILENT MODE]` banner when triggered by heartbeats/cron, along with instructions on how to use the CLI.
- **Requirements for background messaging (silent mode):**
- - The **Bash tool must be enabled** for the agent to run the CLI
- - A user must have messaged the bot at least once (to establish a delivery target) unless you provide an explicit target
- If your agent isn't sending messages during heartbeats, check the [ADE](https://app.letta.com) to see what the agent is doing and whether it's attempting to use `lettabot-message`.
- ## Agent CLI Tools
- LettaBot includes small CLIs the agent can invoke via Bash (or you can run directly):
- ```bash
- lettabot-message send --text "Hello from a background task"
- lettabot-react add --emoji :eyes: --channel discord --chat 123 --message 456
- lettabot-history fetch --limit 25 --channel discord --chat 123456789
- ```
- See [CLI Tools](docs/cli-tools.md) for details and limitations.
- ## Connect to Letta Code
- Any LettaBot agent can also be directly chatted with through [Letta Code](https://github.com/letta-ai/letta-code). Use the `/status` command to find your `agent_id`, and run:
- ```sh
- letta --agent <agent_id>
- ```
- ## OpenAI-Compatible API
- LettaBot exposes `/v1/chat/completions` and `/v1/models` endpoints, so you can use any OpenAI SDK or compatible frontend (like [Open WebUI](https://github.com/open-webui/open-webui)) to chat with your agents:
- ```bash
- curl -X POST http://localhost:8080/v1/chat/completions \
- -H "Content-Type: application/json" \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -d '{"model": "lettabot", "messages": [{"role": "user", "content": "Hello!"}]}'
- ```
- Supports sync and streaming responses. See the [full documentation](docs/openai-compat.md) for Python/Node SDK examples and details.
- ## Security
- ### Network Architecture
- **LettaBot uses outbound connections only** - no public URL or gateway required:
- | Channel | Connection Type | Exposed Ports |
- |---------|-----------------|---------------|
- | Telegram | Long-polling (outbound HTTP) | None |
- | Slack | Socket Mode (outbound WebSocket) | None |
- | Discord | Gateway (outbound WebSocket) | None |
- | WhatsApp | Outbound WebSocket via Baileys | None |
- | Signal | Local daemon on 127.0.0.1 | None |
- ### Tool Execution
- By default, the agent is restricted to **read-only** operations:
- - `Read`, `Glob`, `Grep` - File exploration
- - `web_search` - Internet queries
- - `conversation_search` - Search past messages
- ### Access Control
- LettaBot supports pairing-based access control. When `TELEGRAM_DM_POLICY=pairing`:
- 1. Unauthorized users get a pairing code
- 2. Approve codes via:
- - **Web portal** at `https://your-host/portal` (recommended for cloud deploys)
- - **CLI**: `lettabot pairing approve telegram <CODE>`
- - **API**: `POST /api/v1/pairing/telegram/approve`
- 3. Approved users can then chat with the bot
- ## Development
- ```bash
- # Run in development mode (auto-reload)
- npm run dev
- # Build for production
- npm run build
- # Start production server
- lettabot server
- ```
- ## Releases
- Releases are automated via GitHub Actions. When a version tag is pushed, the workflow builds, tests, generates release notes from merged PRs, and creates a GitHub Release.
- ```bash
- # Create a release
- git tag v0.2.0
- git push origin v0.2.0
- # Create a pre-release (alpha/beta/rc are auto-detected)
- git tag v0.2.0-alpha.1
- git push origin v0.2.0-alpha.1
- ```
- See all releases: [GitHub Releases](https://github.com/letta-ai/lettabot/releases)
- ## Troubleshooting
- **Cannot find package 'keyv'**
- ```
- Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'keyv'
- ```
- Clean reinstall fixes this:
- ```bash
- rm -rf node_modules package-lock.json && npm install
- ```
- **Session errors / "Bad MAC" messages**
- These are normal Signal Protocol renegotiation messages. They're noisy but harmless.
- **Messages going to wrong chat**
- Clear the session and re-link:
- ```bash
- rm -rf ./data/whatsapp-session
- lettabot server # Scan QR again
- ```
- ### Signal
- **Port 8090 already in use**
- ```bash
- SIGNAL_HTTP_PORT=8091
- ```
- ### General
- **Agent not responding**
- Delete the agent store to create a fresh agent:
- ```bash
- lettabot destroy
- ```
- **Heartbeat/cron messages not reaching my chat**
- Heartbeats and cron jobs run in "Silent Mode" - the agent's text output is private and not auto-delivered. To send messages during background tasks, the agent must run:
- ```bash
- lettabot-message send --text "Your message here"
- ```
- Check the [ADE](https://app.letta.com) to see if your agent is attempting to use this command. Common issues:
- - Bash tool not enabled (agent can't run CLI commands)
- - Agent doesn't understand it needs to use the CLI
- - No delivery target set (user never messaged the bot first)
- ## Documentation
- - [Getting Started](docs/getting-started.md)
- - [Docker Server Setup](docs/selfhosted-setup.md) - Run with your own Letta server
- - [Configuration Reference](docs/configuration.md)
- - [OpenAI-Compatible API](docs/openai-compat.md)
- - [Slack Setup](docs/slack-setup.md)
- - [Discord Setup](docs/discord-setup.md)
- - [WhatsApp Setup](docs/whatsapp-setup.md)
- - [Signal Setup](docs/signal-setup.md)
- ## Acknowledgement
- Some skills were adapted from [Moltbot](https://github.com/moltbot/moltbot).
- ## License
- Apache-2.0
src/cli/history-core.test.ts · Bundled script · 123 lines · 1 finding marked
- import { afterEach, describe, expect, it, vi } from 'vitest';
- import { fetchDiscordHistory, fetchHistory, fetchSlackHistory, isValidLimit, parseFetchArgs } from './history-core.js';
- const ORIGINAL_ENV = { ...process.env };
- afterEach(() => {
- for (const key of Object.keys(process.env)) {
- Dismissed after review: Copies every environment variable, where API keys and tokens live, in a file that sends data
- Line 7 on GitHub
- delete process.env[key];
- }
- Object.assign(process.env, ORIGINAL_ENV);
- vi.unstubAllGlobals();
- vi.restoreAllMocks();
- });
- describe('parseFetchArgs', () => {
- it('parses fetch args with flags', () => {
- const parsed = parseFetchArgs([
- '--limit', '25',
- '--channel', 'discord',
- '--chat', '123',
- '--before', '456',
- ]);
- expect(parsed).toEqual({
- channel: 'discord',
- chatId: '123',
- before: '456',
- limit: 25,
- });
- });
- });
- describe('isValidLimit', () => {
- it('accepts positive integers only', () => {
- expect(isValidLimit(1)).toBe(true);
- expect(isValidLimit(50)).toBe(true);
- expect(isValidLimit(0)).toBe(false);
- expect(isValidLimit(-1)).toBe(false);
- expect(isValidLimit(1.5)).toBe(false);
- expect(isValidLimit(Number.NaN)).toBe(false);
- });
- });
- // loadLastTarget is now backed by the Store class (handles v1/v2 transparently).
- // Store-level tests in src/core/store.test.ts cover lastMessageTarget persistence.
- describe('fetchDiscordHistory', () => {
- it('formats Discord history responses', async () => {
- process.env.DISCORD_BOT_TOKEN = 'test-token';
- const fetchSpy = vi.fn().mockResolvedValue({
- ok: true,
- json: async () => ([
- {
- id: '111',
- content: 'Hello',
- author: { username: 'alice', globalName: 'Alice' },
- timestamp: '2026-01-01T00:00:00Z',
- },
- ]),
- });
- vi.stubGlobal('fetch', fetchSpy);
- const output = await fetchDiscordHistory('999', 10, '888');
- const parsed = JSON.parse(output) as {
- count: number;
- messages: Array<{ messageId: string; author: string; content: string; timestamp?: string }>;
- };
- expect(fetchSpy).toHaveBeenCalledWith(
- 'https://discord.com/api/v10/channels/999/messages?limit=10&before=888',
- expect.objectContaining({ method: 'GET' })
- );
- expect(parsed.count).toBe(1);
- expect(parsed.messages[0]).toEqual({
- messageId: '111',
- author: 'Alice',
- content: 'Hello',
- timestamp: '2026-01-01T00:00:00Z',
- });
- });
- });
- describe('fetchSlackHistory', () => {
- it('formats Slack history responses', async () => {
- process.env.SLACK_BOT_TOKEN = 'test-token';
- const fetchSpy = vi.fn().mockResolvedValue({
- ok: true,
- json: async () => ({
- ok: true,
- messages: [
- {
- ts: '1704067200.000100',
- text: 'Hello from Slack',
- user: 'U123456',
- },
- ],
- }),
- });
- vi.stubGlobal('fetch', fetchSpy);
- const output = await fetchSlackHistory('C999', 10);
- const parsed = JSON.parse(output);
- expect(fetchSpy).toHaveBeenCalledWith(
- 'https://slack.com/api/conversations.history',
- expect.objectContaining({ method: 'POST' })
- );
- expect(parsed.count).toBe(1);
- expect(parsed.messages[0].author).toBe('U123456');
- expect(parsed.messages[0].content).toBe('Hello from Slack');
- expect(parsed.messages[0].messageId).toBe('1704067200.000100');
- // Verify ts -> ISO conversion
- expect(parsed.messages[0].timestamp).toBeDefined();
- });
- });
- describe('fetchHistory', () => {
- it('rejects unsupported channels', async () => {
- await expect(fetchHistory('unknown', '1', 1)).rejects.toThrow('Unknown channel');
- });
- });
src/core/redact.test.ts · Bundled script · 103 lines · 2 findings marked
- import { describe, it, expect } from 'vitest';
- import { redactOutbound } from './redact.js';
- describe('redactOutbound', () => {
- describe('secret patterns (default: enabled)', () => {
- it('redacts OpenAI-style API keys', () => {
- expect(redactOutbound('My key is sk-abc123def456ghi789jkl012mno345')).toContain('[REDACTED]');
- expect(redactOutbound('My key is sk-abc123def456ghi789jkl012mno345')).not.toContain('sk-');
- });
- it('redacts GitHub tokens', () => {
- expect(redactOutbound('ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijkl')).toContain('[REDACTED]');
- expect(redactOutbound('ghs_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijkl')).toContain('[REDACTED]');
- expect(redactOutbound('github_pat_ABCDEFGHIJKLMNOPQRSTUVWXYZab')).toContain('[REDACTED]');
- });
- it('redacts Slack tokens', () => {
- expect(redactOutbound('Token: xoxb-123456789-abcdefghij')).toContain('[REDACTED]');
- expect(redactOutbound('xoxp-999-888-777-abcdef')).toContain('[REDACTED]');
- Dismissed after review: Contains what looks like a hardcoded Slack token
- Line 19 on GitHub
- });
- it('redacts AWS access keys', () => {
- expect(redactOutbound('AKIAIOSFODNN7EXAMPLE')).toContain('[REDACTED]');
- });
- it('redacts bearer tokens', () => {
- expect(redactOutbound('Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9')).toContain('[REDACTED]');
- expect(redactOutbound('Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9')).not.toContain('eyJ');
- });
- it('redacts URLs with embedded credentials', () => {
- const url = 'https://admin:s3cretP4ss@database.example.com:5432/mydb';
- expect(redactOutbound(url)).toContain('[REDACTED]');
- expect(redactOutbound(url)).not.toContain('s3cretP4ss');
- });
- it('redacts key=value patterns near sensitive keywords', () => {
- expect(redactOutbound('api_key=abcdef1234567890abcdef1234567890')).toContain('[REDACTED]');
- expect(redactOutbound('token: "aBcDeFgHiJkLmNoPqRsTuVwXyZ012345"')).toContain('[REDACTED]');
- expect(redactOutbound('secret = AAAAABBBBBCCCCCDDDDDEEEEEFFFFF00')).toContain('[REDACTED]');
- });
- it('leaves normal text untouched', () => {
- const text = 'Hello! How are you doing today? The weather is nice.';
- expect(redactOutbound(text)).toBe(text);
- });
- it('leaves short tokens and common words alone', () => {
- const text = 'The key to success is perseverance.';
- expect(redactOutbound(text)).toBe(text);
- });
- it('handles empty and null-ish input', () => {
- expect(redactOutbound('')).toBe('');
- expect(redactOutbound(undefined as unknown as string)).toBe(undefined);
- });
- });
- describe('PII patterns (default: disabled)', () => {
- it('does not redact emails by default', () => {
- expect(redactOutbound('Contact me at user@example.com')).toContain('user@example.com');
- });
- it('redacts emails when PII enabled', () => {
- expect(redactOutbound('Contact me at user@example.com', { pii: true })).not.toContain('user@example.com');
- expect(redactOutbound('Contact me at user@example.com', { pii: true })).toContain('[REDACTED]');
- });
- it('redacts phone numbers when PII enabled', () => {
- expect(redactOutbound('Call me at 555-123-4567', { pii: true })).toContain('[REDACTED]');
- expect(redactOutbound('Call me at (555) 123-4567', { pii: true })).toContain('[REDACTED]');
- expect(redactOutbound('Call me at +1 555 123 4567', { pii: true })).toContain('[REDACTED]');
- });
- });
- describe('config behavior', () => {
- it('secrets enabled by default (no config)', () => {
- expect(redactOutbound('sk-abc123def456ghi789jkl012mno345')).toContain('[REDACTED]');
- });
- it('secrets can be explicitly disabled', () => {
- const text = 'sk-abc123def456ghi789jkl012mno345';
- expect(redactOutbound(text, { secrets: false })).toBe(text);
- });
- it('both layers work together', () => {
- const text = 'Key: sk-abc123def456ghi789jkl012mno345 and email: user@example.com';
- const result = redactOutbound(text, { secrets: true, pii: true });
- expect(result).not.toContain('sk-');
- expect(result).not.toContain('user@example.com');
- });
- });
- describe('multiple matches in one message', () => {
- it('redacts all occurrences', () => {
- const text = 'Keys: sk-aaabbbcccdddeeefffggghhhiiijjjkkk and ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijkl';
- Dismissed after review: Contains what looks like a hardcoded OpenAI API key
- Line 96 on GitHub
- const result = redactOutbound(text);
- expect(result).not.toContain('sk-');
- expect(result).not.toContain('ghp_');
- expect(result.match(/\[REDACTED\]/g)?.length).toBeGreaterThanOrEqual(2);
- });
- });
- });
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.