Skip to content
Back to search

lettabot

SkillWorks with Claude CodeGitHub

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/letta-ai--lettabot/badge.svg)](/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

i

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)

  1. ---
  2. name: lettabot
  3. 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.
  4. ---
  5. # LettaBot Setup
  6. Multi-channel AI assistant with persistent memory across Telegram, Slack, Discord, WhatsApp, and Signal.
  7. ## Quick Setup (Agent-Friendly)
  8. For non-interactive setup (ideal for coding agents):
  9. ```bash
  10. # 1. Clone and install
  11. git clone https://github.com/letta-ai/lettabot.git
  12. cd lettabot
  13. npm install
  14. npm run build
  15. npm link
  16. # 2. Configure required variables
  17. export LETTA_API_KEY="letta_..." # From app.letta.com
  18. # 3. Configure channel (example: Telegram)
  19. export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..." # From @BotFather
  20. # 4. Run non-interactive setup
  21. lettabot onboard --non-interactive
  22. # 5. Start the bot
  23. lettabot server
  24. ```
  25. **Safe defaults used if not set:**
  26. - `LETTA_BASE_URL`: `https://api.letta.com`
  27. - `LETTA_AGENT_NAME`: `"lettabot"`
  28. - Model: selected during `lettabot onboard` or changed with `lettabot model set <handle>`
  29. - `*_DM_POLICY`: `"pairing"` (requires approval before messaging)
  30. - `WHATSAPP_SELF_CHAT_MODE`: `true` (only "Message Yourself" chat)
  31. - `SIGNAL_SELF_CHAT_MODE`: `true` (only "Note to Self")
  32. The setup will show which defaults are being used and validate safety-critical settings.
  33. ## Interactive Setup
  34. For human-friendly setup with wizard:
  35. ```bash
  36. lettabot onboard
  37. ```
  38. The wizard will guide you through:
  39. - Letta API authentication (OAuth or API key)
  40. - Agent selection/creation
  41. - Channel configuration (Telegram, Slack, Discord, WhatsApp, Signal)
  42. ## Environment Variables
  43. ### Authentication
  44. | Variable | Description | Default |
  45. |----------|-------------|---------|
  46. | `LETTA_API_KEY` | API key from app.letta.com | Required (unless using a Docker server) |
  47. | `LETTA_BASE_URL` | API endpoint | `https://api.letta.com` |
  48. ### Agent Selection
  49. | Variable | Description | Default |
  50. |----------|-------------|---------|
  51. | `LETTA_AGENT_ID` | Use existing agent (skip agent creation) | Creates new agent |
  52. | `LETTA_AGENT_NAME` | Name for new agent | `"lettabot"` |
  53. | ~~`LETTA_MODEL`~~ | *Removed* - model is set on the agent server-side. Use `lettabot model set <handle>`. | - |
  54. ### Telegram
  55. | Variable | Description | Required | Default |
  56. |----------|-------------|----------|---------|
  57. | `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather | ✅ | - |
  58. | `TELEGRAM_DM_POLICY` | Access control: `pairing` \| `allowlist` \| `open` | ❌ | `pairing` |
  59. | `TELEGRAM_ALLOWED_USERS` | Comma-separated user IDs (if dmPolicy=allowlist) | ❌ | - |
  60. ### Slack (Socket Mode)
  61. | Variable | Description | Required | Default |
  62. |----------|-------------|----------|---------|
  63. | `SLACK_BOT_TOKEN` | Bot User OAuth Token (xoxb-...) | ✅ | - |
  64. | `SLACK_APP_TOKEN` | App-Level Token (xapp-...) for Socket Mode | ✅ | - |
  65. | `SLACK_APP_NAME` | Custom app name | ❌ | `LETTA_AGENT_NAME` or `"LettaBot"` |
  66. | `SLACK_DM_POLICY` | Access control: `pairing` \| `allowlist` \| `open` | ❌ | `pairing` |
  67. | `SLACK_ALLOWED_USERS` | Comma-separated Slack user IDs (if dmPolicy=allowlist) | ❌ | - |
  68. **Setup Slack app:** See [Slack Setup Wizard](./src/setup/slack-wizard.ts) or run `lettabot onboard` for guided setup.
  69. ### Discord
  70. | Variable | Description | Required | Default |
  71. |----------|-------------|----------|---------|
  72. | `DISCORD_BOT_TOKEN` | Bot token from discord.com/developers/applications | ✅ | - |
  73. | `DISCORD_DM_POLICY` | Access control: `pairing` \| `allowlist` \| `open` | ❌ | `pairing` |
  74. | `DISCORD_ALLOWED_USERS` | Comma-separated Discord user IDs (if dmPolicy=allowlist) | ❌ | - |
  75. **Setup Discord bot:** See [docs/discord-setup.md](./docs/discord-setup.md)
  76. ### WhatsApp
  77. | Variable | Description | Required | Default |
  78. |----------|-------------|----------|---------|
  79. | `WHATSAPP_ENABLED` | Enable WhatsApp: `true` \| `false` | ✅ | - |
  80. | `WHATSAPP_SELF_CHAT_MODE` | Self-chat mode: `true` (personal) \| `false` (dedicated) | ✅ | `true` (safe) |
  81. | `WHATSAPP_DM_POLICY` | Access control: `pairing` \| `allowlist` \| `open` | ❌ | `pairing` |
  82. | `WHATSAPP_ALLOWED_USERS` | Comma-separated phone numbers with + (if dmPolicy=allowlist) | ❌ | - |
  83. **CRITICAL - Read Before Enabling:**
  84. - `WHATSAPP_SELF_CHAT_MODE=true` (personal number): Only responds to "Message Yourself" chat ✅ SAFE
  85. - `WHATSAPP_SELF_CHAT_MODE=false` (dedicated bot number): Responds to ALL incoming messages ⚠️ USE WITH CAUTION
  86. - Default is `true` for safety - bot will NOT message your contacts unless you explicitly set to `false`
  87. **First-Time Setup - QR Code Warning:**
  88. - QR code prints to console when `lettabot server` runs for the first time
  89. - **DO NOT background the server** until after QR code is scanned
  90. - **AI agents using Letta Code or similar**: Output may be truncated! If QR code is not visible:
  91. 1. Tell the agent to stop the server
  92. 2. Run `lettabot server` yourself in a terminal
  93. 3. Scan the QR code when it appears
  94. 4. After pairing, the agent can manage the server normally
  95. - Alternative: Instruct agent "Run lettabot server in FOREGROUND and do NOT background it"
  96. - After initial pairing completes, server can be backgrounded in future runs
  97. ### Signal
  98. | Variable | Description | Required | Default |
  99. |----------|-------------|----------|---------|
  100. | `SIGNAL_PHONE_NUMBER` | Your phone number (with +) | ✅ | - |
  101. | `SIGNAL_DM_POLICY` | Access control: `pairing` \| `allowlist` \| `open` | ❌ | `pairing` |
  102. | `SIGNAL_ALLOWED_USERS` | Comma-separated phone numbers with + (if dmPolicy=allowlist) | ❌ | - |
  103. **Setup:** Requires Signal CLI - see [signal-cli documentation](https://github.com/AsamK/signal-cli).
  104. ## Channel-Specific Setup
  105. ### Telegram Bot Setup
  106. 1. Message [@BotFather](https://t.me/BotFather) on Telegram
  107. 2. Send `/newbot` and follow prompts
  108. 3. Copy the token (format: `123456:ABC-DEF...`)
  109. 4. Set `TELEGRAM_BOT_TOKEN` environment variable
  110. ### Slack App Setup (Interactive)
  111. For Socket Mode (required for real-time messages):
  112. ```bash
  113. lettabot onboard
  114. # Select "Slack" → "Guided setup"
  115. ```
  116. This uses a manifest to pre-configure:
  117. - Socket Mode
  118. - 5 bot scopes (app_mentions:read, chat:write, im:*)
  119. - 2 event subscriptions (app_mention, message.im)
  120. ### Slack App Setup (Manual)
  121. 1. Go to [api.slack.com/apps](https://api.slack.com/apps)
  122. 2. Create app from manifest (see `src/setup/slack-wizard.ts` for manifest YAML)
  123. 3. Install to workspace → copy Bot Token (`xoxb-...`)
  124. 4. Enable Socket Mode → generate App Token (`xapp-...`)
  125. 5. Set both tokens in environment
  126. ## Access Control
  127. Each channel supports three DM policies:
  128. - **`pairing`** (recommended): Users get a code, you approve via CLI (`lettabot pairing approve <channel> <code>`) or API (`POST /api/v1/pairing/<channel>/approve`)
  129. - **`allowlist`**: Only specified user IDs can message
  130. - **`open`**: Anyone can message (not recommended)
  131. ## Conversation Routing
  132. By default, all channels share **one conversation**. You can switch to per-channel conversation histories.
  133. **Single-agent config (top-level):**
  134. ```yaml
  135. conversations:
  136. mode: shared # "shared" (default) or "per-channel"
  137. heartbeat: last-active # "dedicated" | "last-active" | "<channel>"
  138. ```
  139. **Multi-agent config (per agent):**
  140. ```yaml
  141. agents:
  142. - name: MyAgent
  143. conversations:
  144. mode: per-channel
  145. heartbeat: dedicated
  146. ```
  147. Notes:
  148. - `per-channel` means one conversation per **channel adapter** (telegram/slack/discord/etc), not per chat/user.
  149. - Agent memory remains shared across channels; only the conversation history is separated.
  150. - `heartbeat` controls which conversation background triggers use: a dedicated stream, the last active channel, or an explicit channel name.
  151. ## Group Settings (Optional)
  152. Group settings apply to Telegram, Slack, Discord, WhatsApp, and Signal.
  153. **YAML fields (per channel under `channels.<name>`):**
  154. - `groupDebounceSec`: Debounce seconds for group batching (default: 5)
  155. - `groups`: Map of group IDs to config (use `*` as the default)
  156. - `mode`: `open` | `listen` | `mention-only` | `disabled`
  157. - `allowedUsers`: Restrict who can trigger the bot in that group
  158. - `receiveBotMessages`: Allow bot/bot messages (default: false)
  159. - `mentionPatterns`: Extra regex patterns for mention detection (Telegram/WhatsApp/Signal)
  160. - `instantGroups`: Group IDs that bypass batching (**legacy**)
  161. - `groupPollIntervalMin`: Deprecated (minutes)
  162. - `listeningGroups`: Deprecated (use `groups.<id>.mode: listen`)
  163. **Environment variables (non-interactive onboarding):**
  164. Only legacy group options are supported here; prefer editing `lettabot.yaml` for `groups` config.
  165. - `<CHANNEL>_GROUP_DEBOUNCE_SEC` (seconds, e.g. `5`)
  166. - `<CHANNEL>_GROUP_POLL_INTERVAL_MIN` (deprecated, use `_GROUP_DEBOUNCE_SEC` instead)
  167. - `<CHANNEL>_INSTANT_GROUPS` (comma-separated, legacy)
  168. - `<CHANNEL>_LISTENING_GROUPS` (comma-separated, legacy)
  169. Example:
  170. ```yaml
  171. channels:
  172. slack:
  173. enabled: true
  174. botToken: xoxb-...
  175. appToken: xapp-...
  176. groupDebounceSec: 5
  177. mentionPatterns: ["@mybot", "hey bot"]
  178. groups:
  179. "*": { mode: mention-only }
  180. "C0987654321": { mode: listen }
  181. "C0123456789": { mode: open, allowedUsers: ["U123"] }
  182. ```
  183. ## Configuration File
  184. After onboarding, config is saved to `~/.lettabot/config.yaml`:
  185. ```yaml
  186. server:
  187. baseUrl: https://api.letta.com
  188. apiKey: letta_...
  189. agentId: agent-...
  190. conversations:
  191. mode: shared
  192. heartbeat: last-active
  193. channels:
  194. telegram:
  195. enabled: true
  196. botToken: 123456:ABC-DEF...
  197. dmPolicy: pairing
  198. slack:
  199. enabled: true
  200. botToken: xoxb-...
  201. appToken: xapp-...
  202. dmPolicy: pairing
  203. ```
  204. Edit this file directly or re-run `lettabot onboard` to reconfigure.
  205. ## Commands
  206. ```bash
  207. # Setup
  208. lettabot onboard # Interactive wizard
  209. lettabot onboard --non-interactive # Env-based setup (agent-friendly)
  210. # Run
  211. lettabot server # Start bot server
  212. # Manage
  213. lettabot pairing list # List pending pairing requests
  214. lettabot pairing approve <channel> <code> # Approve user
  215. lettabot skills # Enable/disable skills
  216. # Scheduling
  217. lettabot cron list # List scheduled tasks
  218. lettabot cron add "Daily standup at 9am" "0 9 * * *" # Add cron job
  219. ```
  220. ## Troubleshooting
  221. ### "Module not found" errors
  222. Make sure you've run `npm run build` after installing or pulling updates.
  223. ### Telegram bot not responding
  224. 1. Check token is correct: `curl https://api.telegram.org/bot<TOKEN>/getMe`
  225. 2. Ensure bot is started: `lettabot server` should show "Connected to Telegram"
  226. 3. Check access control: User may need pairing approval
  227. ### Slack not receiving messages
  228. 1. Verify Socket Mode is enabled in Slack app settings
  229. 2. Check both tokens are set: `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`
  230. 3. Ensure event subscriptions are configured (app_mention, message.im)
  231. ### WhatsApp QR code not appearing
  232. 1. Make sure Signal Desktop is closed (conflicts with baileys)
  233. 2. Delete `~/.wwebjs_auth` if previously used different library
  234. 3. Check no other WhatsApp Web sessions are active
  235. ## Example: Agent Setup Flow
  236. For coding agents helping users set up LettaBot:
  237. ```bash
  238. # 1. Clone and build
  239. git clone https://github.com/letta-ai/lettabot.git
  240. cd lettabot
  241. npm install && npm run build && npm link
  242. # 2. Get Letta API key
  243. # Guide user to app.letta.com → API Keys → Create Key
  244. # 3. Get Telegram bot token
  245. # Guide user to @BotFather → /newbot → follow prompts
  246. # 4. Set environment variables
  247. export LETTA_API_KEY="letta_..."
  248. export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
  249. # Defaults will be used for LETTA_BASE_URL, agent name, and DM policy
  250. # 5. Run non-interactive setup
  251. lettabot onboard --non-interactive
  252. # 6. Instruct user to start server
  253. # DON'T start server automatically - user must see output
  254. echo "Setup complete! Run 'lettabot server' to start the bot."
  255. ```
  256. **For WhatsApp (QR code required on first run):**
  257. ```bash
  258. export LETTA_API_KEY="letta_..."
  259. export WHATSAPP_ENABLED="true"
  260. export WHATSAPP_SELF_CHAT_MODE="true" # REQUIRED: true=personal number, false=dedicated bot
  261. lettabot onboard --non-interactive
  262. # CRITICAL: Do NOT auto-start the server!
  263. # Tell user: "WhatsApp setup complete. Please run 'lettabot server' in your terminal."
  264. # User must see QR code in console output to scan it.
  265. # After first pairing, server can be managed normally.
  266. ```
  267. **Agent Instructions:**
  268. If an AI agent is helping with setup and WhatsApp is configured:
  269. 1. Complete `lettabot onboard --non-interactive`
  270. 2. **DO NOT** run `lettabot server` automatically
  271. 3. Tell user: "Setup complete! Please run `lettabot server` in a terminal to see the WhatsApp QR code"
  272. 4. Wait for user confirmation that QR was scanned
  273. 5. After confirmation, server can be managed normally
  274. The agent can verify success by checking:
  275. - `lettabot server` output shows "Connected to Telegram" (or other channel)
  276. - Config file exists at `~/.lettabot/config.yaml`
  277. - User can message bot on configured channel(s)
  278. ## Docker Server Letta
  279. To use a Letta Docker server:
  280. ```bash
  281. # Run Letta Docker
  282. docker run -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
  283. -p 8283:8283 \
  284. -e OPENAI_API_KEY="your_openai_api_key" \
  285. letta/letta:latest
  286. # Configure LettaBot
  287. export LETTA_BASE_URL="http://localhost:8283"
  288. export LETTA_API_KEY="sk-..." # From Letta admin panel
  289. lettabot onboard --non-interactive
  290. ```
  291. ## Skills Integration
  292. LettaBot supports loading skills from:
  293. - **Clawdhub** ([clawdhub.com](https://clawdhub.com))
  294. - **skills.sh** repositories
  295. - Local `.skills/` directory
  296. ```bash
  297. # Install skill from Clawdhub
  298. npx molthub@latest install sonoscli
  299. # Connect to LettaBot
  300. lettabot skills
  301. # Space to toggle, Enter to confirm
  302. # Skills will be available to agent
  303. ```
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)

  1. <div align="center">
  2. # LettaBot is deprecated
  3. </div>
  4. > [!WARNING]
  5. > **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).
  6. >
  7. > **Where to go instead:**
  8. > - **Telegram / Slack messaging** → [Channels](https://docs.letta.com/letta-code/channels) — same agent, same memory, integrated into Letta Code directly
  9. > - **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
  10. > - **Heartbeats and scheduled tasks** → [letta cron](https://docs.letta.com/letta-code/scheduling) — built into remote environments
  11. >
  12. > Existing LettaBot deployments will continue to function, but for any new project, use Channels + Remote Environments. Migration is typically straightforward (~20 minutes).
  13. >
  14. > **Need migration help?** Ask in the `#ezra` channel on the [Letta Discord](https://discord.gg/letta).
  15. ---
  16. # LettaBot
  17. 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).
  18. <img width="750" alt="lettabot-preview" src="assets/preview.jpg" />
  19. [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/lettabot?utm_medium=integration&utm_source=template&utm_campaign=generic)
  20. [![Discord](https://img.shields.io/badge/discord-join-blue?style=flat-square&logo=discord)](https://discord.gg/letta)
  21. > [!IMPORTANT]
  22. > *"Help! I need help with my LettaBot!"* 👋
  23. >
  24. > 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.
  25. ## Features
  26. - **Multi-Channel** - Chat seamlessly across Telegram, Slack, Discord, WhatsApp, and Signal
  27. - **Feed Ingestion** - Read-only Bluesky Jetstream stream for selected DID(s)
  28. - **Unified Memory** - Single agent remembers everything from all channels
  29. - **Persistent Memory** - Agent remembers conversations across sessions (days/weeks/months)
  30. - **Local Tool Execution** - Agent can read files, search code, run commands on your machine
  31. - **Voice Messages** - Automatic transcription via OpenAI Whisper
  32. - **Heartbeat** - Periodic check-ins where the agent reviews tasks
  33. - **Scheduling** - Agent can create one-off reminders and recurring tasks
  34. - **Streaming Responses** - Real-time message updates as the agent thinks
  35. ## Quick Start
  36. ### Prerequisites
  37. - Node.js 20+
  38. - A Letta API key from [app.letta.com](https://app.letta.com) (or a running [Letta Docker server](https://docs.letta.com/guides/docker/))
  39. - A Telegram bot token from [@BotFather](https://t.me/BotFather)
  40. - Optional: a ChatGPT subscription account you want to use for model credits
  41. ### Install
  42. ```bash
  43. # Clone the repository
  44. git clone https://github.com/letta-ai/lettabot.git
  45. cd lettabot
  46. # Install dependencies
  47. npm install
  48. # Build and link the CLI globally
  49. npm run build
  50. npm link
  51. ```
  52. ### Update
  53. ```bash
  54. # Pull latest changes
  55. git pull origin main
  56. # Reinstall dependencies and rebuild
  57. npm install
  58. npm run build
  59. ```
  60. #### Optional: Run a Letta Docker server
  61. You can use `lettabot` with a Docker server with:
  62. ```
  63. docker run \
  64. -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
  65. -p 8283:8283 \
  66. -e OPENAI_API_KEY="your_openai_api_key" \
  67. letta/letta:latest
  68. ```
  69. See the [documentation](https://docs.letta.com/guides/docker/) for more details on running with Docker.
  70. ### Setup
  71. **Option 1: AI-Assisted Setup (Recommended)**
  72. Paste this into Letta Code, Claude Code, Cursor, or any AI coding assistant:
  73. ```
  74. Clone https://github.com/letta-ai/lettabot, read the SKILL.md
  75. for setup instructions, and help me configure Telegram.
  76. ```
  77. You'll need:
  78. - A Letta API key from [app.letta.com](https://app.letta.com) (or a [Letta Docker server](https://docs.letta.com/guides/docker/))
  79. - A Telegram bot token from [@BotFather](https://t.me/BotFather)
  80. The AI will handle cloning, installing, and configuration autonomously.
  81. **Option 2: Interactive Wizard**
  82. For manual step-by-step setup:
  83. ```bash
  84. git clone https://github.com/letta-ai/lettabot.git
  85. cd lettabot
  86. npm install && npm run build && npm link
  87. lettabot onboard
  88. ```
  89. Prefer to use your ChatGPT subscription instead of another API key? After onboarding (or anytime), run:
  90. ```bash
  91. lettabot connect chatgpt
  92. ```
  93. This opens a browser flow and enables connected subscription handles in the model picker.
  94. ### Run
  95. ```bash
  96. lettabot server
  97. ```
  98. That's it! Message your bot on Telegram.
  99. > **Note:** For detailed environment variable reference and multi-channel setup, see [SKILL.md](./SKILL.md)
  100. ## Voice
  101. 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.
  102. **Supported channels:** Telegram, WhatsApp, Signal, Slack, Discord
  103. See [docs/voice.md](./docs/voice.md) for full setup, configuration, and troubleshooting.
  104. ## Skills
  105. LettaBot is compatible with [skills.sh](https://skills.sh) and [Clawdhub](https://clawdhub.com/).
  106. ```bash
  107. # from Clawdhub
  108. npx molthub@latest install sonoscli
  109. # from skills.sh
  110. npm run skills:add supabase/agent-skills
  111. # connect to LettaBot
  112. lettabot skills
  113. ◆ Enable skills (space=toggle, enter=confirm):
  114. │ ◻ ── ClawdHub Skills ── (~/clawd/skills)
  115. │ ◻ 🦞 sonoscli
  116. │ ◻ ── Vercel Skills ── (~/.agents/skills)
  117. │ ◻ 🔼 supabase/agent-skills
  118. │ ◻ ── Built-in Skills ──
  119. │ ◻ 📦 1password
  120. │ ◻ ...
  121. # View LettaBot skills
  122. lettabot skills status
  123. ```
  124. ### Home Assistant
  125. Control your smart home with LettaBot:
  126. ```bash
  127. # 1. Install the skill from ClawdHub
  128. npx clawdhub@latest install homeassistant
  129. # 2. Enable the skill
  130. lettabot skills sync
  131. # Select "homeassistant" from the list
  132. # 3. Configure credentials (see skill docs for details)
  133. # You'll need: HA URL + Long-Lived Access Token
  134. ```
  135. Then ask your bot things like:
  136. - "Turn off the living room lights"
  137. - "What's the temperature in the bedroom?"
  138. - "Set the thermostat to 72"
  139. ## CLI Commands
  140. | Command | Description |
  141. |---------|-------------|
  142. | `lettabot onboard` | Interactive setup wizard |
  143. | `lettabot connect` | Connect model providers (for example, `chatgpt`) |
  144. | `lettabot server` | Start the bot server |
  145. | `lettabot configure` | View and edit configuration |
  146. | `lettabot skills status` | Show enabled and available skills |
  147. | `lettabot destroy` | Delete all local data and start fresh |
  148. | `lettabot help` | Show help |
  149. ## Channel Setup
  150. By default, LettaBot uses a **single agent with a single shared conversation** across all channels:
  151. ```
  152. Telegram ──┐
  153. Slack ─────┤
  154. Discord ───┼──→ ONE AGENT ──→ ONE CONVERSATION
  155. WhatsApp ──┤ (memory) (chat history)
  156. Signal ────┘
  157. ```
  158. - Start a conversation on Telegram
  159. - Continue it on Slack
  160. - Pick it up on WhatsApp
  161. - The agent remembers everything!
  162. You can also enable **per-channel conversations** (one conversation per channel adapter, not per chat/user):
  163. ```
  164. Telegram ──→ CONVERSATION (telegram)
  165. Slack ─────→ CONVERSATION (slack)
  166. Discord ───→ CONVERSATION (discord)
  167. WhatsApp ──→ CONVERSATION (whatsapp)
  168. Signal ────→ CONVERSATION (signal)
  169. (shared agent memory across channels)
  170. ```
  171. Configure in `lettabot.yaml`:
  172. ```yaml
  173. conversations:
  174. mode: shared # default: one conversation across all channels
  175. heartbeat: last-active # "dedicated" | "last-active" | "<channel>"
  176. ```
  177. For multi-agent configs, the same block lives under each agent:
  178. ```yaml
  179. agents:
  180. - name: MyAgent
  181. conversations:
  182. mode: per-channel
  183. heartbeat: dedicated
  184. ```
  185. | Channel | Guide | Requirements |
  186. |---------|-------|--------------|
  187. | Telegram | [Setup Guide](docs/getting-started.md) | Bot token from @BotFather |
  188. | Slack | [Setup Guide](docs/slack-setup.md) | Slack app with Socket Mode |
  189. | Discord | [Setup Guide](docs/discord-setup.md) | Discord bot + Message Content Intent |
  190. | WhatsApp | [Setup Guide](docs/whatsapp-setup.md) | Phone with WhatsApp |
  191. | Signal | [Setup Guide](docs/signal-setup.md) | signal-cli + phone number |
  192. | Bluesky (read-only) | [Setup Guide](docs/bluesky-setup.md) | Jetstream WebSocket + DID filter |
  193. At least one channel is required. Telegram is the easiest to start with.
  194. ### Group Settings (Optional)
  195. Configure group batching and per-group response modes in `lettabot.yaml`:
  196. ```yaml
  197. channels:
  198. slack:
  199. groupDebounceSec: 5
  200. mentionPatterns: ["@mybot", "hey bot"]
  201. groups:
  202. "*": { mode: mention-only } # default for all groups
  203. "C0987654321": { mode: listen } # observe, only reply on mention
  204. "C0123456789": { mode: open, allowedUsers: ["U123"] }
  205. ```
  206. Group modes:
  207. - `open`: process + respond to all group messages
  208. - `listen`: process for memory, but auto-replies only on mention
  209. - `mention-only`: only process when mentioned
  210. - `disabled`: ignore all group messages
  211. Notes:
  212. - `instantGroups` still bypasses batching (legacy).
  213. - `listeningGroups` and `groups.<id>.requireMention` are deprecated; use `groups.<id>.mode`.
  214. See `SKILL.md` for the full environment variable list and examples.
  215. ## Bot Commands
  216. | Command | Description |
  217. |---------|-------------|
  218. | `/start` | Welcome message and help |
  219. | `/status` | Show current session info |
  220. | `/heartbeat` | Manually trigger a heartbeat check-in |
  221. ## Background Tasks (Heartbeats & Cron)
  222. Heartbeats always run in **Silent Mode**. Cron jobs are **silent by default**, but can auto-deliver responses when created with `--deliver channel:chatId`.
  223. 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.
  224. To send messages during silent mode, the agent must explicitly use the CLI:
  225. ```bash
  226. lettabot-message send --text "Hey, I found something interesting!"
  227. ```
  228. The agent sees a clear `[SILENT MODE]` banner when triggered by heartbeats/cron, along with instructions on how to use the CLI.
  229. **Requirements for background messaging (silent mode):**
  230. - The **Bash tool must be enabled** for the agent to run the CLI
  231. - A user must have messaged the bot at least once (to establish a delivery target) unless you provide an explicit target
  232. 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`.
  233. ## Agent CLI Tools
  234. LettaBot includes small CLIs the agent can invoke via Bash (or you can run directly):
  235. ```bash
  236. lettabot-message send --text "Hello from a background task"
  237. lettabot-react add --emoji :eyes: --channel discord --chat 123 --message 456
  238. lettabot-history fetch --limit 25 --channel discord --chat 123456789
  239. ```
  240. See [CLI Tools](docs/cli-tools.md) for details and limitations.
  241. ## Connect to Letta Code
  242. 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:
  243. ```sh
  244. letta --agent <agent_id>
  245. ```
  246. ## OpenAI-Compatible API
  247. 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:
  248. ```bash
  249. curl -X POST http://localhost:8080/v1/chat/completions \
  250. -H "Content-Type: application/json" \
  251. -H "Authorization: Bearer YOUR_API_KEY" \
  252. -d '{"model": "lettabot", "messages": [{"role": "user", "content": "Hello!"}]}'
  253. ```
  254. Supports sync and streaming responses. See the [full documentation](docs/openai-compat.md) for Python/Node SDK examples and details.
  255. ## Security
  256. ### Network Architecture
  257. **LettaBot uses outbound connections only** - no public URL or gateway required:
  258. | Channel | Connection Type | Exposed Ports |
  259. |---------|-----------------|---------------|
  260. | Telegram | Long-polling (outbound HTTP) | None |
  261. | Slack | Socket Mode (outbound WebSocket) | None |
  262. | Discord | Gateway (outbound WebSocket) | None |
  263. | WhatsApp | Outbound WebSocket via Baileys | None |
  264. | Signal | Local daemon on 127.0.0.1 | None |
  265. ### Tool Execution
  266. By default, the agent is restricted to **read-only** operations:
  267. - `Read`, `Glob`, `Grep` - File exploration
  268. - `web_search` - Internet queries
  269. - `conversation_search` - Search past messages
  270. ### Access Control
  271. LettaBot supports pairing-based access control. When `TELEGRAM_DM_POLICY=pairing`:
  272. 1. Unauthorized users get a pairing code
  273. 2. Approve codes via:
  274. - **Web portal** at `https://your-host/portal` (recommended for cloud deploys)
  275. - **CLI**: `lettabot pairing approve telegram <CODE>`
  276. - **API**: `POST /api/v1/pairing/telegram/approve`
  277. 3. Approved users can then chat with the bot
  278. ## Development
  279. ```bash
  280. # Run in development mode (auto-reload)
  281. npm run dev
  282. # Build for production
  283. npm run build
  284. # Start production server
  285. lettabot server
  286. ```
  287. ## Releases
  288. 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.
  289. ```bash
  290. # Create a release
  291. git tag v0.2.0
  292. git push origin v0.2.0
  293. # Create a pre-release (alpha/beta/rc are auto-detected)
  294. git tag v0.2.0-alpha.1
  295. git push origin v0.2.0-alpha.1
  296. ```
  297. See all releases: [GitHub Releases](https://github.com/letta-ai/lettabot/releases)
  298. ## Troubleshooting
  299. ### WhatsApp
  300. **Cannot find package 'keyv'**
  301. ```
  302. Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'keyv'
  303. ```
  304. Clean reinstall fixes this:
  305. ```bash
  306. rm -rf node_modules package-lock.json && npm install
  307. ```
  308. **Session errors / "Bad MAC" messages**
  309. These are normal Signal Protocol renegotiation messages. They're noisy but harmless.
  310. **Messages going to wrong chat**
  311. Clear the session and re-link:
  312. ```bash
  313. rm -rf ./data/whatsapp-session
  314. lettabot server # Scan QR again
  315. ```
  316. ### Signal
  317. **Port 8090 already in use**
  318. ```bash
  319. SIGNAL_HTTP_PORT=8091
  320. ```
  321. ### General
  322. **Agent not responding**
  323. Delete the agent store to create a fresh agent:
  324. ```bash
  325. lettabot destroy
  326. ```
  327. **Heartbeat/cron messages not reaching my chat**
  328. 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:
  329. ```bash
  330. lettabot-message send --text "Your message here"
  331. ```
  332. Check the [ADE](https://app.letta.com) to see if your agent is attempting to use this command. Common issues:
  333. - Bash tool not enabled (agent can't run CLI commands)
  334. - Agent doesn't understand it needs to use the CLI
  335. - No delivery target set (user never messaged the bot first)
  336. ## Documentation
  337. - [Getting Started](docs/getting-started.md)
  338. - [Docker Server Setup](docs/selfhosted-setup.md) - Run with your own Letta server
  339. - [Configuration Reference](docs/configuration.md)
  340. - [OpenAI-Compatible API](docs/openai-compat.md)
  341. - [Slack Setup](docs/slack-setup.md)
  342. - [Discord Setup](docs/discord-setup.md)
  343. - [WhatsApp Setup](docs/whatsapp-setup.md)
  344. - [Signal Setup](docs/signal-setup.md)
  345. ## Acknowledgement
  346. Some skills were adapted from [Moltbot](https://github.com/moltbot/moltbot).
  347. ## License
  348. Apache-2.0
src/cli/history-core.test.ts · Bundled script · 123 lines · 1 finding marked
  1. import { afterEach, describe, expect, it, vi } from 'vitest';
  2. import { fetchDiscordHistory, fetchHistory, fetchSlackHistory, isValidLimit, parseFetchArgs } from './history-core.js';
  3. const ORIGINAL_ENV = { ...process.env };
  4. afterEach(() => {
  5. 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
  6. delete process.env[key];
  7. }
  8. Object.assign(process.env, ORIGINAL_ENV);
  9. vi.unstubAllGlobals();
  10. vi.restoreAllMocks();
  11. });
  12. describe('parseFetchArgs', () => {
  13. it('parses fetch args with flags', () => {
  14. const parsed = parseFetchArgs([
  15. '--limit', '25',
  16. '--channel', 'discord',
  17. '--chat', '123',
  18. '--before', '456',
  19. ]);
  20. expect(parsed).toEqual({
  21. channel: 'discord',
  22. chatId: '123',
  23. before: '456',
  24. limit: 25,
  25. });
  26. });
  27. });
  28. describe('isValidLimit', () => {
  29. it('accepts positive integers only', () => {
  30. expect(isValidLimit(1)).toBe(true);
  31. expect(isValidLimit(50)).toBe(true);
  32. expect(isValidLimit(0)).toBe(false);
  33. expect(isValidLimit(-1)).toBe(false);
  34. expect(isValidLimit(1.5)).toBe(false);
  35. expect(isValidLimit(Number.NaN)).toBe(false);
  36. });
  37. });
  38. // loadLastTarget is now backed by the Store class (handles v1/v2 transparently).
  39. // Store-level tests in src/core/store.test.ts cover lastMessageTarget persistence.
  40. describe('fetchDiscordHistory', () => {
  41. it('formats Discord history responses', async () => {
  42. process.env.DISCORD_BOT_TOKEN = 'test-token';
  43. const fetchSpy = vi.fn().mockResolvedValue({
  44. ok: true,
  45. json: async () => ([
  46. {
  47. id: '111',
  48. content: 'Hello',
  49. author: { username: 'alice', globalName: 'Alice' },
  50. timestamp: '2026-01-01T00:00:00Z',
  51. },
  52. ]),
  53. });
  54. vi.stubGlobal('fetch', fetchSpy);
  55. const output = await fetchDiscordHistory('999', 10, '888');
  56. const parsed = JSON.parse(output) as {
  57. count: number;
  58. messages: Array<{ messageId: string; author: string; content: string; timestamp?: string }>;
  59. };
  60. expect(fetchSpy).toHaveBeenCalledWith(
  61. 'https://discord.com/api/v10/channels/999/messages?limit=10&before=888',
  62. expect.objectContaining({ method: 'GET' })
  63. );
  64. expect(parsed.count).toBe(1);
  65. expect(parsed.messages[0]).toEqual({
  66. messageId: '111',
  67. author: 'Alice',
  68. content: 'Hello',
  69. timestamp: '2026-01-01T00:00:00Z',
  70. });
  71. });
  72. });
  73. describe('fetchSlackHistory', () => {
  74. it('formats Slack history responses', async () => {
  75. process.env.SLACK_BOT_TOKEN = 'test-token';
  76. const fetchSpy = vi.fn().mockResolvedValue({
  77. ok: true,
  78. json: async () => ({
  79. ok: true,
  80. messages: [
  81. {
  82. ts: '1704067200.000100',
  83. text: 'Hello from Slack',
  84. user: 'U123456',
  85. },
  86. ],
  87. }),
  88. });
  89. vi.stubGlobal('fetch', fetchSpy);
  90. const output = await fetchSlackHistory('C999', 10);
  91. const parsed = JSON.parse(output);
  92. expect(fetchSpy).toHaveBeenCalledWith(
  93. 'https://slack.com/api/conversations.history',
  94. expect.objectContaining({ method: 'POST' })
  95. );
  96. expect(parsed.count).toBe(1);
  97. expect(parsed.messages[0].author).toBe('U123456');
  98. expect(parsed.messages[0].content).toBe('Hello from Slack');
  99. expect(parsed.messages[0].messageId).toBe('1704067200.000100');
  100. // Verify ts -> ISO conversion
  101. expect(parsed.messages[0].timestamp).toBeDefined();
  102. });
  103. });
  104. describe('fetchHistory', () => {
  105. it('rejects unsupported channels', async () => {
  106. await expect(fetchHistory('unknown', '1', 1)).rejects.toThrow('Unknown channel');
  107. });
  108. });
src/core/redact.test.ts · Bundled script · 103 lines · 2 findings marked
  1. import { describe, it, expect } from 'vitest';
  2. import { redactOutbound } from './redact.js';
  3. describe('redactOutbound', () => {
  4. describe('secret patterns (default: enabled)', () => {
  5. it('redacts OpenAI-style API keys', () => {
  6. expect(redactOutbound('My key is sk-abc123def456ghi789jkl012mno345')).toContain('[REDACTED]');
  7. expect(redactOutbound('My key is sk-abc123def456ghi789jkl012mno345')).not.toContain('sk-');
  8. });
  9. it('redacts GitHub tokens', () => {
  10. expect(redactOutbound('ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijkl')).toContain('[REDACTED]');
  11. expect(redactOutbound('ghs_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijkl')).toContain('[REDACTED]');
  12. expect(redactOutbound('github_pat_ABCDEFGHIJKLMNOPQRSTUVWXYZab')).toContain('[REDACTED]');
  13. });
  14. it('redacts Slack tokens', () => {
  15. expect(redactOutbound('Token: xoxb-123456789-abcdefghij')).toContain('[REDACTED]');
  16. expect(redactOutbound('xoxp-999-888-777-abcdef')).toContain('[REDACTED]');
    • Dismissed after review: Contains what looks like a hardcoded Slack token
    • Line 19 on GitHub
  17. });
  18. it('redacts AWS access keys', () => {
  19. expect(redactOutbound('AKIAIOSFODNN7EXAMPLE')).toContain('[REDACTED]');
  20. });
  21. it('redacts bearer tokens', () => {
  22. expect(redactOutbound('Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9')).toContain('[REDACTED]');
  23. expect(redactOutbound('Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9')).not.toContain('eyJ');
  24. });
  25. it('redacts URLs with embedded credentials', () => {
  26. const url = 'https://admin:s3cretP4ss@database.example.com:5432/mydb';
  27. expect(redactOutbound(url)).toContain('[REDACTED]');
  28. expect(redactOutbound(url)).not.toContain('s3cretP4ss');
  29. });
  30. it('redacts key=value patterns near sensitive keywords', () => {
  31. expect(redactOutbound('api_key=abcdef1234567890abcdef1234567890')).toContain('[REDACTED]');
  32. expect(redactOutbound('token: "aBcDeFgHiJkLmNoPqRsTuVwXyZ012345"')).toContain('[REDACTED]');
  33. expect(redactOutbound('secret = AAAAABBBBBCCCCCDDDDDEEEEEFFFFF00')).toContain('[REDACTED]');
  34. });
  35. it('leaves normal text untouched', () => {
  36. const text = 'Hello! How are you doing today? The weather is nice.';
  37. expect(redactOutbound(text)).toBe(text);
  38. });
  39. it('leaves short tokens and common words alone', () => {
  40. const text = 'The key to success is perseverance.';
  41. expect(redactOutbound(text)).toBe(text);
  42. });
  43. it('handles empty and null-ish input', () => {
  44. expect(redactOutbound('')).toBe('');
  45. expect(redactOutbound(undefined as unknown as string)).toBe(undefined);
  46. });
  47. });
  48. describe('PII patterns (default: disabled)', () => {
  49. it('does not redact emails by default', () => {
  50. expect(redactOutbound('Contact me at user@example.com')).toContain('user@example.com');
  51. });
  52. it('redacts emails when PII enabled', () => {
  53. expect(redactOutbound('Contact me at user@example.com', { pii: true })).not.toContain('user@example.com');
  54. expect(redactOutbound('Contact me at user@example.com', { pii: true })).toContain('[REDACTED]');
  55. });
  56. it('redacts phone numbers when PII enabled', () => {
  57. expect(redactOutbound('Call me at 555-123-4567', { pii: true })).toContain('[REDACTED]');
  58. expect(redactOutbound('Call me at (555) 123-4567', { pii: true })).toContain('[REDACTED]');
  59. expect(redactOutbound('Call me at +1 555 123 4567', { pii: true })).toContain('[REDACTED]');
  60. });
  61. });
  62. describe('config behavior', () => {
  63. it('secrets enabled by default (no config)', () => {
  64. expect(redactOutbound('sk-abc123def456ghi789jkl012mno345')).toContain('[REDACTED]');
  65. });
  66. it('secrets can be explicitly disabled', () => {
  67. const text = 'sk-abc123def456ghi789jkl012mno345';
  68. expect(redactOutbound(text, { secrets: false })).toBe(text);
  69. });
  70. it('both layers work together', () => {
  71. const text = 'Key: sk-abc123def456ghi789jkl012mno345 and email: user@example.com';
  72. const result = redactOutbound(text, { secrets: true, pii: true });
  73. expect(result).not.toContain('sk-');
  74. expect(result).not.toContain('user@example.com');
  75. });
  76. });
  77. describe('multiple matches in one message', () => {
  78. it('redacts all occurrences', () => {
  79. const text = 'Keys: sk-aaabbbcccdddeeefffggghhhiiijjjkkk and ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijkl';
    • Dismissed after review: Contains what looks like a hardcoded OpenAI API key
    • Line 96 on GitHub
  80. const result = redactOutbound(text);
  81. expect(result).not.toContain('sk-');
  82. expect(result).not.toContain('ghp_');
  83. expect(result.match(/\[REDACTED\]/g)?.length).toBeGreaterThanOrEqual(2);
  84. });
  85. });
  86. });

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.