telechatai 1.0.0__tar.gz

telechatai-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 telechatai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

telechatai-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+include requirements.txt
+recursive-include scripts *

telechatai-1.0.0/PKG-INFO

@@ -0,0 +1,372 @@
+Metadata-Version: 2.4
+Name: telechatai
+Version: 1.0.0
+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