telechatai 1.1.5

Claude AI on your phone/desktop — personal, self-hosted messenger bot for Telegram, WhatsApp, and Slack

Telechat

Claude AI on your phone / desktop — personal, self-hosted, zero-infrastructure.
Supports WhatsApp, Telegram, and Slack simultaneously from a single process.

A bot that connects to Claude AI via two modes:

• CLI mode — Uses the Claude Code CLI (claude). No API key needed if you have a Claude subscription.
• API mode — Uses the Anthropic API directly. Requires an API key. Works in Docker.

Install

npm install -g telechat
telechat init

That's it. telechat init walks you through each platform interactively using Claude CLI — it opens the right pages, grabs your tokens, validates everything, and writes your config.

Requires: Claude Code CLI (npm install -g @anthropic-ai/claude-code && claude auth login)

Alternative installs

# pip
pip install telechatai
telechat init

# npx (no global install)
npx telechat init

# From source
git clone https://github.com/telechatai/telechat.git
cd telechat && pip install -e .
telechat init

Manual setup (no Claude CLI)

telechat setup

Step-by-step wizard with prompts. Works without Claude CLI.

Commands

telechat              # Start bot as background service
telechat stop         # Stop the bot
telechat restart      # Restart the bot
telechat status       # Check if running
telechat logs         # Tail the bot log
telechat env          # Show environment variables (tokens masked)
telechat env clean    # Remove .env file (clear all credentials)
telechat clean        # Same as env clean
telechat init         # AI-guided setup using Claude CLI
telechat setup        # Manual setup wizard
telechat update       # Update to latest version
telechat --debug      # Start with verbose logging
telechat --version    # Show version
telechat --help       # Show all commands

The bot runs as a background service — it survives terminal close and Ctrl+C. Manage it with start/stop/restart/status.

---

Platform comparison

	Telegram	WhatsApp	Slack
Bridge	Telegram Bot API	Green API free tier	Slack Bolt + Socket Mode
Setup	Talk to @BotFather	Scan a QR code	Create a Slack app
Photo / file support	Yes	Text only	Text only
Interactive UI	Inline buttons	No	Reactions as status indicator
Works without public URL	Yes (polling)	Yes (polling)	Yes (WebSocket)
Works on corporate Wi-Fi	Depends	Yes	Yes

---

Setup

1 — Choose your platform(s)

Set BOT_MODE in .env — accepts a comma-separated list or a shorthand:

Value	What starts
telegram	Telegram only (default)
whatsapp	WhatsApp only
slack	Slack only
telegram,slack	Telegram + Slack
telegram,whatsapp	Telegram + WhatsApp
both	Telegram + WhatsApp (legacy alias)
all	All three platforms

---

2a — Telegram setup

1. Open Telegram Web: https://web.telegram.org/k/
2. Log in by scanning the QR code:
   • Open Telegram on your phone
   • Go to Settings → Devices → Link Desktop Device
   • Point your phone camera at the QR code
3. Search for @BotFather and send /newbot
4. Pick a display name and a username (must end in bot)
5. Copy the token → set TELEGRAM_BOT_TOKEN in .env

Finding your user ID (for access control)

1. Search for @userinfobot in Telegram Web
2. Send any message — it replies with your numeric ID
3. Copy the ID → set TELEGRAM_ALLOWED_USER_IDS in .env

Optional: customize your bot

BotFather command	What it does
/setdescription	Text users see before starting the bot
/setabouttext	Bio shown on the bot's profile
/setuserpic	Profile picture
/setcommands	Register autocomplete hints

Register command hints:

start - Welcome message
reset - Clear conversation history
mode - Show current mode and model
id - Show your Telegram user ID

---

2b — Slack setup (Socket Mode — no public URL needed)

Corporate workspace? Most company Slack workspaces block individual users from installing apps. Create a free personal workspace at slack.com/get-started instead.

Step-by-step

1. Go to https://api.slack.com/apps → Create New App → From scratch

   • Enter a name (e.g. "TeleChat") and select your workspace

2. Socket Mode → toggle ON

   • Create an App-Level Token: name it telechat, add scope connections:write
   • Copy the xapp-... token → this is SLACK_APP_TOKEN

3. OAuth & Permissions → scroll to Bot Token Scopes → add:

   Scope	Purpose
   chat:write	Send messages
   channels:history	Read public channel messages
   groups:history	Read private channel messages
   im:history	Read DMs
   im:write	Open DM conversations
   app_mentions:read	Detect @mentions
   reactions:write	Show ⏳ while Claude thinks

4. Event Subscriptions → toggle ON → Subscribe to bot events: message.im, message.channels, message.groups, app_mention → Save Changes

5. Install App → Install to Workspace → Allow

   • Copy the Bot User OAuth Token (xoxb-...) → this is SLACK_BOT_TOKEN
   • ⚠ NOT the User OAuth Token (xoxp-/xoxe-) — that won't work

6. Find your Slack member ID: click your profile pic → Profile → ⋮ → Copy member ID

.env for Slack

BOT_MODE=slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_ALLOWED_USER_IDS=U01234567

How it works

Trigger	How to use
Direct message	Just message the bot
Channel	@yourbot <question>
Thread	Reply mentioning the bot to keep conversation in-thread

A ⏳ reaction appears on your message while Claude is thinking, removed when done.

---

2c — WhatsApp setup (Green API — free, no Meta account needed)

1. Sign up at https://console.green-api.com (free Developer plan)
2. You'll see a free instance on the dashboard
3. Find idInstance (a number) and apiTokenInstance (a long hex string) at the top of your instance
4. Link your WhatsApp phone:
   • Click your instance → look for the QR code section
   • On your phone: WhatsApp → Settings → Linked Devices → Link a Device
   • Scan the QR code with your phone camera
5. Copy credentials into .env:

BOT_MODE=whatsapp
GREEN_API_INSTANCE_ID=1234567890
GREEN_API_TOKEN=your_token_here
WHATSAPP_ALLOWED_NUMBERS=919876543210   # your number without the +

Corporate network note: Green API works over standard HTTPS polling — no webhook or public URL needed.

---

3 — Configure Claude

Variable	Default	Description
CLAUDE_MODE	cli	cli or api
ANTHROPIC_API_KEY	—	Required for API mode
CLAUDE_MODEL	claude-sonnet-4-20250514	API mode model
SYSTEM_PROMPT	(generic)	Your personal instructions to Claude
CLAUDE_CLI_WORK_DIR	~	Working directory for CLI
CLAUDE_CLI_ADD_DIRS	—	Comma-separated extra dirs Claude can access
CLAUDE_CLI_PERMISSION_MODE	—	acceptEdits / auto / bypassPermissions
CLAUDE_CLI_MODEL	sonnet	CLI model: haiku / sonnet / opus
CLAUDE_TIMEOUT	180	Seconds to wait for Claude
RATE_LIMIT_REQUESTS	20	Max messages per window
RATE_LIMIT_WINDOW	60	Rate limit window (seconds)

CLI mode — requires Claude Code CLI installed and authenticated:

npm install -g @anthropic-ai/claude-code
claude auth login

API mode:

CLAUDE_MODE=api
ANTHROPIC_API_KEY=sk-ant-...

---

Running

The bot runs as a background service by default:

telechat              # Start
telechat stop         # Stop
telechat restart      # Restart
telechat status       # Check status
telechat logs         # Tail logs
telechat --debug      # Start with verbose logging

From source

./scripts/start.sh                  # Foreground
./scripts/service.sh install        # macOS launchd / Linux systemd

Docker (API mode only)

docker compose up -d
docker logs -f telechat

---

Telegram commands

Core

Command	Description
/start	Welcome message
/reset	Clear conversation history
/mode	Show current mode and model
/model	Switch model (haiku / sonnet / opus)
/engine	Switch between CLI and API mode
/settings	View all current settings
/verbose	Set output verbosity
/permissions	Change CLI permission mode
/usage	Show usage statistics
/budget	Set daily/monthly cost limits
/id	Show your Telegram user ID

Sessions

Command	Description
/sessions	List all sessions
/new	Create a new session
/switch	Switch to another session
/rename	Rename a session
/pin	Pin/unpin a session
/archive	Archive a session
/resume	Resume a Claude CLI session
/fork	Fork current session into a new one

Memory

Command	Description
/remember	Save a memory
/recall	Search memories
/memories	List all memories
/forget	Delete a memory
/editmem	Edit a memory
/exportmem	Export memories as JSON
/importmem	Import memories from JSON

Tools

Command	Description
/code	Start a coding task
/project	Set working project directory
/plan	Multi-step planning agent
/search	Web search
/fetch	Fetch and summarize a URL
/web	Browse a webpage
/kb	Knowledge base (upload/search docs)
/imagine	Generate an image
/tts	Text-to-speech
/music	Generate music
/video	Generate video
/poll	Create a poll
/schedule	Schedule a task

---

WhatsApp usage

Just send a message. There are no slash commands — WhatsApp is intentionally kept simple.

---

Project structure

├── telechat_pkg/
│   ├── main.py              Entry point — reads BOT_MODE, starts adapters
│   ├── claude_core.py       Claude CLI/API invocation layer
│   ├── store.py             SQLite persistence, sessions, history
│   ├── telegram_bot.py      Telegram adapter
│   ├── whatsapp_bot.py      WhatsApp adapter (Green API polling)
│   ├── slack_bot.py         Slack adapter (Socket Mode)
│   ├── memory.py            Per-user memory with FTS5 search
│   ├── session_manager.py   Multi-session conversation management
│   ├── knowledge_base.py    Document store with chunking and search
│   ├── cost_budget.py       Usage tracking and budget alerts
│   ├── coder.py             Chat-based coding agent (/code, /project)
│   ├── two_agent.py         Multi-step planning agent
│   ├── smart_router.py      Model routing by query complexity
│   ├── health.py            Health checks and circuit breaker
│   ├── web_fetch.py         URL content extraction (Jina / raw)
│   ├── link_understanding.py  Auto-detect and fetch URLs in messages
│   ├── tts.py               Text-to-speech via OpenAI
│   ├── image_gen.py         Image generation
│   ├── music_gen.py         Music generation
│   ├── video_gen.py         Video generation
│   └── ...
├── scripts/
│   ├── watchdog.py          Auto-restart and self-healing
│   └── publish.sh           PyPI + npm release script
├── npm/bin/telechat.js      CLI entry point
├── Dockerfile               (API mode only)
├── docker-compose.yml
├── requirements.txt
└── .env.example

---

Features

• Three platforms — Telegram, WhatsApp, and Slack from one process (BOT_MODE=all)
• One-command setup — npm install -g telechat && telechat init
• Background service — runs detached, survives terminal close
• AI-guided setup — telechat init uses Claude CLI for interactive configuration
• Dual Claude mode — CLI (free with Claude subscription) or API
• Coding agent — /code and /project for end-to-end development tasks
• Memory system — per-user memories with FTS5 search, remembered across sessions
• Multi-session conversations — create, switch, pin, archive named sessions
• Knowledge base — upload documents, search with full-text and semantic matching
• Two-agent planning — multi-step task execution with progress updates
• Smart model routing — auto-selects haiku / sonnet / opus by query complexity
• Cost tracking & budgets — daily/monthly limits with alerts
• Web fetch & link understanding — auto-extracts content from URLs in messages
• Media generation — TTS, image, music, and video generation
• Health monitoring — HTTP health endpoint, circuit breakers, auto-recovery watchdog
• Image & file analysis — Telegram photos + documents
• Typing indicator — shows "typing…" while Claude processes
• Model switching — haiku / sonnet / opus from Telegram inline buttons
• Rate limiting — configurable per-user throttling
• Persistent history — SQLite with WAL mode, async writes, history caching
• Markdown rendering — formatted responses with plain-text fallback

---

Security

• Set TELEGRAM_ALLOWED_USER_IDS, WHATSAPP_ALLOWED_NUMBERS, or SLACK_ALLOWED_USER_IDS to restrict access
• View credentials with telechat env (tokens are masked)
• Clear all credentials with telechat clean
• Never commit .env — it is in .gitignore
• In CLI mode the bot inherits your Claude auth — don't run on untrusted machines

---

Troubleshooting

Symptom	Fix
telechat: command not found	Run npm install -g telechat or use npx telechat
Bot not responding	Check telechat status and telechat logs
Telegram 409 conflict	Another instance is running — telechat stop then telechat start
WhatsApp: no replies	Check instance status in Green API console — must be authorized
Slack: "error creating request"	Corporate workspace blocks installs — use a free personal workspace
Slack: bot doesn't respond	Check Socket Mode is enabled; App-Level Token needs connections:write
Slack: wrong token type	Use Bot User OAuth Token (xoxb-...), not User OAuth Token (xoxp-/xoxe-)
Slack: works in channels not DMs	Add im:history + im:write scopes and reinstall to workspace
claude: command not found	Install Claude Code CLI: npm i -g @anthropic-ai/claude-code
Response cut off	Bot auto-chunks at 4 000 chars per message — expected
Bot stops after reboot	Use ./scripts/service.sh install for a system service

---

License

MIT