Metadata-Version: 2.4
Name: telechatai
Version: 1.0.1
Summary: Claude AI on your phone/desktop — personal, self-hosted messenger bot for Telegram, WhatsApp, and Slack
Author: telechatai
License-Expression: MIT
Project-URL: Homepage, https://github.com/telechatai/telechat
Project-URL: Repository, https://github.com/telechatai/telechat
Project-URL: Issues, https://github.com/telechatai/telechat/issues
Keywords: telechat,claude,telegram,whatsapp,slack,chatbot,ai,anthropic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-telegram-bot>=21.6
Requires-Dist: anthropic>=0.99.0
Requires-Dist: requests>=2.32.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: slack-bolt>=1.21.0
Dynamic: license-file

# 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

```bash
# npm (auto-installs Python deps on first run)
npm install -g telechat
telechat

# pip
pip install telechat
telechat
```

## Quick Start (from source)

```bash
# Clone
git clone https://github.com/telechatai/telechat.git
cd telechat

# Install
./scripts/install.sh

# Edit .env with your tokens
nano .env

# Run
./scripts/start.sh
```

## Platform comparison

| | Telegram | WhatsApp | Slack |
|--|----------|----------|-------|
| Bridge | Telegram Bot API | [Green API](https://green-api.com) 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 and search for **@BotFather** (verified blue checkmark).
2. Send `/newbot` and follow the prompts.
3. Copy the token → set `TELEGRAM_BOT_TOKEN` 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
```

**Finding your user ID (for `ALLOWED_USER_IDS`)**

1. Start your bot and send `/id`
2. Copy the numeric ID → paste into `ALLOWED_USER_IDS` in `.env`

---

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

> **Corporate / enterprise workspace?** Most company Slack workspaces (e.g. Intuit) block
> individual users from installing new apps. If you hit _"An error occurred while creating
> your request"_, create a **free personal workspace** at [slack.com/get-started](https://slack.com/get-started)
> and install the bot there instead. You're the admin — no approval needed. Invite your
> teammates to the personal workspace to share the bot.

#### Step-by-step

1. Go to <https://api.slack.com/apps> → **Create New App** → **From scratch**  
   _(pick your personal workspace, not a corporate one)_

2. **Settings → Socket Mode → Enable**  
   → **Create an App-Level Token** → name it anything → scope: `connections:write`  
   → copy the `xapp-1-...` token — this is `SLACK_APP_TOKEN`

3. **OAuth & Permissions → Bot Token Scopes** → add all of these:

   | 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 → Enable** → Subscribe to bot events:  
   `message.im`, `message.channels`, `message.groups`, `app_mention`  
   → **Save Changes**

5. **OAuth & Permissions → Install to Workspace** → Allow  
   → copy the `xoxb-...` Bot Token — this is `SLACK_BOT_TOKEN`

6. In your Slack workspace, invite the bot to any channel: `/invite @yourbot`

#### `.env` for Slack

```env
BOT_MODE=slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-1-...

# Your Slack member ID to restrict access (leave empty to allow everyone)
# Find it: click your name → View profile → ⋯ → Copy member ID
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>
2. Click **Create instance** → choose **Developer** plan (free — 1 500 msg/month)
3. In the instance dashboard → **Scan QR** → scan with your WhatsApp phone
4. Copy **Instance ID** and **API Token** → paste into `.env`:

```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. If Telegram is blocked on your network, use
> `BOT_MODE=whatsapp` instead.

---

### 3 — Configure Claude

All Claude settings apply to both platforms:

| 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:

```bash
# Install Claude Code CLI: https://docs.anthropic.com/en/docs/claude-code
claude auth login
```

**API mode:**

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

---

## Running

### Foreground

```bash
./scripts/start.sh
```

### As a system service (macOS launchd / Linux systemd)

```bash
./scripts/service.sh install    # Install and start
./scripts/service.sh status     # Check status
./scripts/service.sh logs       # Tail logs
./scripts/service.sh restart    # Restart
./scripts/service.sh stop       # Stop
./scripts/service.sh uninstall  # Remove service
```

### Docker (API mode only)

```bash
# Set CLAUDE_MODE=api in .env
docker compose up -d
docker logs -f telechat
```

---

## Telegram commands

| Command | Description |
|---------|-------------|
| `/start` | Welcome message |
| `/reset` | Clear conversation history |
| `/mode` | Show current mode and model |
| `/model` | Switch model (haiku / sonnet / opus) |
| `/verbose` | Set output verbosity: 0 quiet · 1 normal · 2 detailed |
| `/permissions` | Change CLI permission mode |
| `/usage` | Show usage statistics |
| `/id` | Show your Telegram user ID |

---

## WhatsApp usage

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

---

## Project structure

```
├── main.py            Entry point — reads BOT_MODE, starts adapters
├── claude_core.py     Shared: Claude CLI/API, SQLite history, rate limiting
├── telegram_bot.py    Telegram adapter
├── whatsapp_bot.py    WhatsApp adapter (Green API polling)
├── slack_bot.py       Slack adapter (Socket Mode)
├── bot.py             Backward-compat shim (runs Telegram, same as before)
├── scripts/
│   ├── install.sh
│   ├── start.sh
│   └── service.sh
├── Dockerfile         (API mode only)
├── docker-compose.yml
├── requirements.txt
└── .env.example
```

---

## Features

- **Three platforms** — Telegram, WhatsApp, and Slack from one process (`BOT_MODE=all`)
- **Dual Claude mode** — CLI (free with Claude subscription) or API
- **Typing indicator** — shows "typing…" while Claude processes
- **Image & file analysis** — Telegram only (photos + documents)
- **Model switching** — haiku / sonnet / opus from Telegram inline buttons
- **Verbose mode** — see what tools Claude is using
- **Rate limiting** — configurable per-user throttling
- **Persistent history** — SQLite, keyed per platform+user; survives restarts
- **Usage tracking** — per-user message and token statistics
- **Markdown rendering** — formatted responses with plain-text fallback

---

## Per-developer sharing

Each developer runs their **own instance** on their own machine:

1. Clone this repo
2. `./scripts/install.sh`
3. Set their own credentials + `SYSTEM_PROMPT` in `.env`
4. `./scripts/start.sh`

No shared server. No shared credentials. Fully private.

---

## Security

- Set `ALLOWED_USER_IDS` (Telegram) or `WHATSAPP_ALLOWED_NUMBERS` to restrict who can use your bot
- 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 |
|---------|-----|
| WhatsApp: no replies | Check instance status in Green API console — must be `authorized` |
| Slack: "error creating request" on install | Corporate workspace blocks app installs — create a free personal workspace at [slack.com/get-started](https://slack.com/get-started) instead |
| Slack: bot doesn't respond | Check Socket Mode is enabled; App-Level Token must have `connections:write` scope |
| Slack: works in channels but not DMs | Add `im:history` + `im:write` scopes and reinstall the app to workspace |
| Slack: missing messages after reinstall | Re-subscribe to events (`message.im`, `message.channels`, etc.) under Event Subscriptions |
| Telegram: SSL/handshake error | Telegram may be blocked on your network; use `BOT_MODE=slack` or `BOT_MODE=whatsapp` |
| `claude: command not found` | Install Claude Code CLI and ensure it's in PATH |
| Response cut off | Bot auto-chunks at 4 000 chars per message — expected |
| Bot stops after reboot | Use `./scripts/service.sh install` for a proper system service |

---

## License

MIT
