ctb 1.0.0

package/.env.example

@@ -0,0 +1,76 @@
+# Claude Telegram Bot - Environment Configuration
+
+# ==============================================================================
+# REQUIRED
+# ==============================================================================
+
+# Telegram bot token from @BotFather
+TELEGRAM_BOT_TOKEN=1234567890:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
+
+# Comma-separated Telegram user IDs allowed to use the bot
+# Find your ID: message @userinfobot on Telegram
+TELEGRAM_ALLOWED_USERS=123456789
+
+# ==============================================================================
+# RECOMMENDED
+# ==============================================================================
+
+# Working directory where Claude runs (loads CLAUDE.md, skills, MCP config)
+CLAUDE_WORKING_DIR=/Users/yourname/personal
+
+# OpenAI API key for voice message transcription
+# Without this, voice messages won't work
+OPENAI_API_KEY=sk-...
+
+# ==============================================================================
+# OPTIONAL - Security
+# ==============================================================================
+
+# Comma-separated paths Claude can access
+# Default: working dir, ~/Documents, ~/Downloads, ~/Desktop, ~/.claude
+# Note: Setting this OVERRIDES defaults. Include ~/.claude for plan mode to work.
+# ALLOWED_PATHS=/Users/yourname/personal,/Users/yourname/projects,/Users/yourname/.claude
+
+# Rate limiting (token bucket)
+# RATE_LIMIT_ENABLED=true
+# RATE_LIMIT_REQUESTS=20
+# RATE_LIMIT_WINDOW=60
+
+# ==============================================================================
+# OPTIONAL - Claude Authentication
+# ==============================================================================
+
+# API key for environments without Claude Code CLI auth
+# Get from: https://console.anthropic.com/
+# Note: API usage is billed per token - CLI auth is more cost-effective
+# ANTHROPIC_API_KEY=sk-ant-api03-...
+
+# Path to Claude CLI (auto-detected from PATH by default)
+# CLAUDE_CLI_PATH=/usr/local/bin/claude
+
+# ==============================================================================
+# OPTIONAL - Extended Thinking
+# ==============================================================================
+
+# Keywords that trigger extended thinking (comma-separated, case-insensitive)
+# THINKING_KEYWORDS=think,pensa,ragiona
+
+# Keywords that trigger deep thinking (50k tokens)
+# THINKING_DEEP_KEYWORDS=ultrathink,think hard,pensa bene
+
+# ==============================================================================
+# OPTIONAL - Voice Transcription
+# ==============================================================================
+
+# Additional context for voice transcription (names, technical terms, etc.)
+# TRANSCRIPTION_CONTEXT=Common names: John, Alice. Tech: Kubernetes, GraphQL.
+
+# ==============================================================================
+# OPTIONAL - Logging
+# ==============================================================================
+
+# Audit log path
+# AUDIT_LOG_PATH=/tmp/claude-telegram-audit.log
+
+# Output audit logs as JSON (default: human-readable)
+# AUDIT_LOG_JSON=false

package/CLAUDE.md

@@ -0,0 +1,116 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+bun run start      # Run the bot
+bun run dev        # Run with auto-reload (--watch)
+bun run typecheck  # Run TypeScript type checking
+bun install        # Install dependencies
+```
+
+## Architecture
+
+This is a Telegram bot (~3,300 lines TypeScript) that lets you control Claude Code from your phone via text, voice, photos, and documents. Built with Bun and grammY.
+
+### Message Flow
+
+```
+Telegram message → Handler → Auth check → Rate limit → Claude session → Streaming response → Audit log
+```
+
+### Key Modules
+
+- **`src/index.ts`** - Entry point, registers handlers, starts polling
+- **`src/config.ts`** - Environment parsing, MCP loading, safety prompts
+- **`src/session.ts`** - `ClaudeSession` class wrapping Agent SDK V2 with streaming, session persistence (`/tmp/claude-telegram-session.json`), and defense-in-depth safety checks
+- **`src/security.ts`** - `RateLimiter` (token bucket), path validation, command safety checks
+- **`src/formatting.ts`** - Markdown→HTML conversion for Telegram, tool status emoji formatting
+- **`src/utils.ts`** - Audit logging, voice transcription (OpenAI), typing indicators
+- **`src/types.ts`** - Shared TypeScript types
+
+### Handlers (`src/handlers/`)
+
+Each message type has a dedicated async handler:
+- **`commands.ts`** - `/start`, `/new`, `/stop`, `/status`, `/resume`, `/restart`
+- **`text.ts`** - Text messages with intent filtering
+- **`voice.ts`** - Voice→text via OpenAI, then same flow as text
+- **`photo.ts`** - Image analysis with media group buffering (1s timeout for albums)
+- **`document.ts`** - PDF extraction (pdftotext CLI) and text file processing
+- **`callback.ts`** - Inline keyboard button handling for ask_user MCP
+- **`streaming.ts`** - Shared `StreamingState` and status callback factory
+
+### Security Layers
+
+1. User allowlist (`TELEGRAM_ALLOWED_USERS`)
+2. Rate limiting (token bucket, configurable)
+3. Path validation (`ALLOWED_PATHS`)
+4. Command safety (blocked patterns)
+5. System prompt constraints
+6. Audit logging
+
+### Configuration
+
+All config via `.env` (copy from `.env.example`). Key variables:
+- `TELEGRAM_BOT_TOKEN`, `TELEGRAM_ALLOWED_USERS` (required)
+- `CLAUDE_WORKING_DIR` - Working directory for Claude
+- `ALLOWED_PATHS` - Directories Claude can access
+- `OPENAI_API_KEY` - For voice transcription
+
+MCP servers defined in `mcp-config.ts`.
+
+### Runtime Files
+
+- `/tmp/claude-telegram-session.json` - Session persistence for `/resume`
+- `/tmp/telegram-bot/` - Downloaded photos/documents
+- `/tmp/claude-telegram-audit.log` - Audit log
+
+## Patterns
+
+**Adding a command**: Create handler in `commands.ts`, register in `index.ts` with `bot.command("name", handler)`
+
+**Adding a message handler**: Create in `handlers/`, export from `index.ts`, register in `index.ts` with appropriate filter
+
+**Streaming pattern**: All handlers use `createStatusCallback()` from `streaming.ts` and `session.sendMessageStreaming()` for live updates.
+
+**Type checking**: Run `bun run typecheck` periodically while editing TypeScript files. Fix any type errors before committing.
+
+**After code changes**: Restart the bot so changes can be tested. Use `launchctl kickstart -k gui/$(id -u)/com.claude-telegram-ts` if running as a service, or `bun run start` for manual runs.
+
+## Standalone Build
+
+The bot can be compiled to a standalone binary with `bun build --compile`. This is used by the ClaudeBot macOS app wrapper.
+
+### External Dependencies
+
+PDF extraction uses `pdftotext` CLI instead of an npm package (to avoid bundling issues):
+
+```bash
+brew install poppler  # Provides pdftotext
+```
+
+### PATH Requirements
+
+When running as a standalone binary (especially from a macOS app), the PATH may not include Homebrew. The launcher must ensure PATH includes:
+- `/opt/homebrew/bin` (Apple Silicon Homebrew)
+- `/usr/local/bin` (Intel Homebrew)
+
+Without this, `pdftotext` won't be found and PDF parsing will fail silently with an error message.
+
+## Commit Style
+
+Do not add "Generated with Claude Code" footers or "Co-Authored-By" trailers to commit messages.
+
+## Running as Service (macOS)
+
+```bash
+cp launchagent/com.claude-telegram-ts.plist.template ~/Library/LaunchAgents/com.claude-telegram-ts.plist
+# Edit plist with your paths
+launchctl load ~/Library/LaunchAgents/com.claude-telegram-ts.plist
+
+# Logs
+tail -f /tmp/claude-telegram-bot-ts.log
+tail -f /tmp/claude-telegram-bot-ts.err
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fabrizio Rinaldi
+
+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.

package/Makefile

@@ -0,0 +1,142 @@
+# Claude Telegram Bot - Makefile
+# Usage: make <target>
+
+SHELL := /bin/bash
+
+PLIST_NAME := com.claude-telegram-ts
+PLIST_PATH := ~/Library/LaunchAgents/$(PLIST_NAME).plist
+PLIST_TEMPLATE := launchagent/$(PLIST_NAME).plist.template
+LOG_FILE := /tmp/claude-telegram-bot.log
+ERR_FILE := /tmp/claude-telegram-bot.err
+
+.PHONY: help install setup run dev stop start restart status logs logs-err clean typecheck test
+
+# Default target
+help:
+	@echo "Claude Telegram Bot"
+	@echo ""
+	@echo "Quick start:"
+	@echo "  make setup      - First-time setup (install deps, create .env)"
+	@echo "  make run        - Run bot in foreground"
+	@echo "  make dev        - Run with auto-reload (watch mode)"
+	@echo ""
+	@echo "Background service (macOS LaunchAgent):"
+	@echo "  make start      - Install and start background service"
+	@echo "  make stop       - Stop background service"
+	@echo "  make restart    - Restart background service"
+	@echo "  make status     - Check if service is running"
+	@echo "  make logs       - Tail stdout logs"
+	@echo "  make logs-err   - Tail stderr logs"
+	@echo "  make uninstall  - Remove background service"
+	@echo ""
+	@echo "Development:"
+	@echo "  make install    - Install dependencies"
+	@echo "  make test       - Run tests"
+	@echo "  make typecheck  - Run TypeScript type check"
+	@echo "  make clean      - Remove temp files and logs"
+
+# Install dependencies
+install:
+	bun install
+
+# First-time setup
+setup: install
+	@if [ ! -f .env ]; then \
+		cp .env.example .env; \
+		echo "Created .env from template"; \
+		echo ">>> Edit .env with your TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS"; \
+	else \
+		echo ".env already exists"; \
+	fi
+	@echo ""
+	@echo "Next steps:"
+	@echo "  1. Edit .env with your credentials"
+	@echo "  2. Run 'make run' to test"
+	@echo "  3. Run 'make start' to run as background service"
+
+# Run in foreground
+run:
+	bun run start
+
+# Run with watch mode
+dev:
+	bun run dev
+
+# Run tests
+test:
+	bun test
+
+# TypeScript type check
+typecheck:
+	bun run typecheck
+
+# === Background Service (macOS LaunchAgent) ===
+
+# Install and start service
+start:
+	@if [ ! -f .env ]; then \
+		echo "Error: .env not found. Run 'make setup' first."; \
+		exit 1; \
+	fi
+	@echo "Installing LaunchAgent..."
+	@mkdir -p ~/Library/LaunchAgents
+	@export $$(grep -v '^#' .env | xargs) && \
+	sed -e "s|/Users/USERNAME/.bun/bin/bun|$$(command -v bun)|g" \
+	    -e "s|/Users/USERNAME/Dev/claude-telegram-bot-ts|$$(pwd)|g" \
+	    -e "s|<string>/Users/USERNAME/Dev</string>|<string>$${CLAUDE_WORKING_DIR:-$$(pwd)}</string>|g" \
+	    -e "s|your-bot-token-here|$${TELEGRAM_BOT_TOKEN}|g" \
+	    -e "s|<string>123456789</string>|<string>$${TELEGRAM_ALLOWED_USERS}</string>|g" \
+	    -e "s|<string>sk-...</string>|<string>$${OPENAI_API_KEY:-}</string>|g" \
+	    -e "s|USERNAME|$$(whoami)|g" \
+	    $(PLIST_TEMPLATE) > $(PLIST_PATH)
+	@echo "Created $(PLIST_PATH) with values from .env"
+	@launchctl unload $(PLIST_PATH) 2>/dev/null || true
+	@launchctl load $(PLIST_PATH)
+	@echo "Service started. Check 'make logs' for output."
+
+# Stop service
+stop:
+	@launchctl unload $(PLIST_PATH) 2>/dev/null || echo "Service not running"
+	@echo "Service stopped"
+
+# Restart service
+restart:
+	@launchctl kickstart -k gui/$$(id -u)/$(PLIST_NAME) 2>/dev/null || \
+		(echo "Service not loaded. Run 'make start' first." && exit 1)
+	@echo "Service restarted"
+
+# Check service status
+status:
+	@if launchctl list | grep -q $(PLIST_NAME); then \
+		echo "Service: RUNNING"; \
+		launchctl list $(PLIST_NAME); \
+	else \
+		echo "Service: NOT RUNNING"; \
+	fi
+
+# Uninstall service
+uninstall: stop
+	@rip $(PLIST_PATH) 2>/dev/null || true
+	@echo "Service uninstalled"
+
+# Tail stdout logs
+logs:
+	@if [ -f $(LOG_FILE) ]; then \
+		tail -f $(LOG_FILE); \
+	else \
+		echo "No log file yet. Start the service first."; \
+	fi
+
+# Tail stderr logs
+logs-err:
+	@if [ -f $(ERR_FILE) ]; then \
+		tail -f $(ERR_FILE); \
+	else \
+		echo "No error log yet."; \
+	fi
+
+# Clean temp files
+clean:
+	rip $(LOG_FILE) $(ERR_FILE) 2>/dev/null || true
+	rip /tmp/telegram-bot 2>/dev/null || true
+	@echo "Cleaned temp files"

package/README.md

@@ -0,0 +1,268 @@
+# Claude Telegram Bot
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Bun](https://img.shields.io/badge/Bun-1.0+-black.svg)](https://bun.sh/)
+
+**Turn [Claude Code](https://claude.com/product/claude-code) into your personal assistant, accessible from anywhere via Telegram.**
+
+Send text, voice, photos, and documents. See responses and tools usage in real-time.
+
+![Demo](assets/demo.gif)
+
+## Claude Code as a Personal Assistant
+
+I've started using Claude Code as a personal assistant, and I've built this bot so I can access it from anywhere.
+
+In fact, while Claude Code is described as a powerful AI **coding agent**, it's actually a very capable **general-purpose agent** too when given the right instructions, context, and tools.
+
+To achieve this, I set up a folder with a CLAUDE.md that teaches Claude about me (my preferences, where my notes live, my workflows), has a set of tools and scripts based on my needs, and pointed this bot at that folder.
+
+→ **[📄 See the Personal Assistant Guide](docs/personal-assistant-guide.md)** for detailed setup and examples.
+
+## Bot Features
+
+- 💬 **Text**: Ask questions, give instructions, have conversations
+- 🎤 **Voice**: Speak naturally - transcribed via OpenAI and processed by Claude
+- 📸 **Photos**: Send screenshots, documents, or anything visual for analysis
+- 📄 **Documents**: PDFs, text files, and archives (ZIP, TAR) are extracted and analyzed
+- 🔄 **Session persistence**: Conversations continue across messages
+- 📨 **Message queuing**: Send multiple messages while Claude works - they queue up automatically. Prefix with `!` or use `/stop` to interrupt and send immediately
+- 🧠 **Extended thinking**: Trigger Claude's reasoning by using words like "think" or "reason" - you'll see its thought process as it works (configurable via `THINKING_TRIGGER_KEYWORDS`)
+- 🔘 **Interactive buttons**: Claude can present options as tappable inline buttons via the built-in `ask_user` MCP tool
+
+## Quick Start
+
+### Install via npm (Recommended)
+
+```bash
+# Install globally
+npm install -g ctb
+
+# Run in any project directory
+cd ~/my-project
+ctb
+```
+
+On first run, `ctb` will prompt for your Telegram bot token and allowed user IDs, then optionally save them to `.env`.
+
+**Run multiple instances:** Each project directory gets its own isolated bot session. Open multiple terminals and run `ctb` in different directories.
+
+### Install from Source
+
+```bash
+git clone https://github.com/htlin/claude-telegram-bot
+cd claude-telegram-bot
+
+cp .env.example .env
+# Edit .env with your credentials
+
+bun install
+bun run start
+```
+
+### Prerequisites
+
+- **Bun 1.0+** - [Install Bun](https://bun.sh/)
+- **Claude Agent SDK** - `@anthropic-ai/claude-agent-sdk` (installed via bun install)
+- **Telegram Bot Token** from [@BotFather](https://t.me/BotFather)
+- **OpenAI API Key** (optional, for voice transcription)
+
+### Claude Authentication
+
+The bot uses the `@anthropic-ai/claude-agent-sdk` which supports two authentication methods:
+
+| Method                     | Best For                                | Setup                             |
+| -------------------------- | --------------------------------------- | --------------------------------- |
+| **CLI Auth** (recommended) | High usage, cost-effective              | Run `claude` once to authenticate |
+| **API Key**                | CI/CD, environments without Claude Code | Set `ANTHROPIC_API_KEY` in `.env` |
+
+**CLI Auth** (recommended): The SDK automatically uses your Claude Code login. Just ensure you've run `claude` at least once and authenticated. This uses your Claude Code subscription which is much more cost-effective for heavy usage.
+
+**API Key**: For environments where Claude Code isn't installed. Get a key from [console.anthropic.com](https://console.anthropic.com/) and add to `.env`:
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-api03-...
+```
+
+Note: API usage is billed per token and can get expensive quickly for heavy use.
+
+## Configuration
+
+### 1. Create Your Bot
+
+1. Open [@BotFather](https://t.me/BotFather) on Telegram
+2. Send `/newbot` and follow the prompts to create your bot
+3. Copy the token (looks like `1234567890:ABC-DEF...`)
+
+Then send `/setcommands` to BotFather and paste this:
+
+```
+start - Show status and user ID
+new - Start a fresh session
+resume - Resume last session
+stop - Interrupt current query
+status - Check what Claude is doing
+cd - Change working directory
+bookmarks - Manage directory bookmarks
+restart - Restart the bot
+```
+
+### 2. Configure Environment
+
+Create `.env` with your settings:
+
+```bash
+# Required
+TELEGRAM_BOT_TOKEN=1234567890:ABC-DEF...   # From @BotFather
+TELEGRAM_ALLOWED_USERS=123456789           # Your Telegram user ID
+
+# Recommended
+CLAUDE_WORKING_DIR=/path/to/your/folder    # Where Claude runs (loads CLAUDE.md, skills, MCP)
+OPENAI_API_KEY=sk-...                      # For voice transcription
+```
+
+**Finding your Telegram user ID:** Message [@userinfobot](https://t.me/userinfobot) on Telegram.
+
+**File access paths:** By default, Claude can access:
+
+- `CLAUDE_WORKING_DIR` (or home directory if not set)
+- `~/Documents`, `~/Downloads`, `~/Desktop`
+- `~/.claude` (for Claude Code plans and settings)
+
+To customize, set `ALLOWED_PATHS` in `.env` (comma-separated). Note: this **overrides** all defaults, so include `~/.claude` if you want plan mode to work:
+
+```bash
+ALLOWED_PATHS=/your/project,/other/path,~/.claude
+```
+
+### 3. Configure MCP Servers (Optional)
+
+Copy and edit the MCP config:
+
+```bash
+cp mcp-config.ts mcp-config.local.ts
+# Edit mcp-config.local.ts with your MCP servers
+```
+
+The bot includes a built-in `ask_user` MCP server that lets Claude present options as tappable inline keyboard buttons. Add your own MCP servers (Things, Notion, Typefully, etc.) to give Claude access to your tools.
+
+## Bot Commands
+
+| Command      | Description                       |
+| ------------ | --------------------------------- |
+| `/start`     | Show status and your user ID      |
+| `/new`       | Start a fresh session             |
+| `/resume`    | Resume last session after restart |
+| `/stop`      | Interrupt current query           |
+| `/status`    | Check what Claude is doing        |
+| `/cd <path>` | Change working directory          |
+| `/bookmarks` | Manage directory bookmarks        |
+| `/restart`   | Restart the bot                   |
+
+### Directory Navigation
+
+Use `/cd` and `/bookmarks` to quickly switch between project directories:
+
+```
+/cd ~/projects/myapp     # Change to directory, shows "Add to bookmarks" button
+/cd                      # Show current working directory
+/bookmarks               # List saved bookmarks with navigation buttons
+```
+
+Each bookmark shows two buttons:
+
+- **🆕 Name** - Start a new session in that directory
+- **🗑️** - Remove from bookmarks
+
+## Running as a Service (macOS)
+
+```bash
+cp launchagent/com.claude-telegram-ts.plist.template ~/Library/LaunchAgents/com.claude-telegram-ts.plist
+# Edit the plist with your paths and env vars
+launchctl load ~/Library/LaunchAgents/com.claude-telegram-ts.plist
+```
+
+The bot will start automatically on login and restart if it crashes.
+
+**Prevent sleep:** To keep the bot running when your Mac is idle, go to **System Settings → Battery → Options** and enable **"Prevent automatic sleeping when the display is off"** (when on power adapter).
+
+**Logs:**
+
+```bash
+tail -f /tmp/claude-telegram-bot-ts.log   # stdout
+tail -f /tmp/claude-telegram-bot-ts.err   # stderr
+```
+
+**Shell aliases:** If running as a service, these aliases make it easy to manage the bot (add to `~/.zshrc` or `~/.bashrc`):
+
+```bash
+alias cbot='launchctl list | grep com.claude-telegram-ts'
+alias cbot-stop='launchctl bootout gui/$(id -u)/com.claude-telegram-ts 2>/dev/null && echo "Stopped"'
+alias cbot-start='launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-telegram-ts.plist 2>/dev/null && echo "Started"'
+alias cbot-restart='launchctl kickstart -k gui/$(id -u)/com.claude-telegram-ts && echo "Restarted"'
+alias cbot-logs='tail -f /tmp/claude-telegram-bot-ts.log'
+```
+
+## Development
+
+```bash
+# Run with auto-reload
+bun --watch run src/index.ts
+
+# Type check
+bun run typecheck
+
+# Or directly
+bun run --bun tsc --noEmit
+```
+
+## Security
+
+> **⚠️ Important:** This bot runs Claude Code with **all permission prompts bypassed**. Claude can read, write, and execute commands without confirmation within the allowed paths. This is intentional for a seamless mobile experience, but you should understand the implications before deploying.
+
+**→ [Read the full Security Model](SECURITY.md)** for details on how permissions work and what protections are in place.
+
+Multiple layers protect against misuse:
+
+1. **User allowlist** - Only your Telegram IDs can use the bot
+2. **Intent classification** - AI filter blocks dangerous requests
+3. **Path validation** - File access restricted to `ALLOWED_PATHS`
+4. **Command safety** - Destructive patterns like `rm -rf /` are blocked
+5. **Rate limiting** - Prevents runaway usage
+6. **Audit logging** - All interactions logged to `/tmp/claude-telegram-audit.log`
+
+## Troubleshooting
+
+**Bot doesn't respond**
+
+- Verify your user ID is in `TELEGRAM_ALLOWED_USERS`
+- Check the bot token is correct
+- Look at logs: `tail -f /tmp/claude-telegram-bot-ts.err`
+- Ensure the bot process is running
+
+**Claude authentication issues**
+
+- For CLI auth: run `claude` in terminal and verify you're logged in
+- For API key: check `ANTHROPIC_API_KEY` is set and starts with `sk-ant-api03-`
+- Verify the API key has credits at [console.anthropic.com](https://console.anthropic.com/)
+
+**Voice messages fail**
+
+- Ensure `OPENAI_API_KEY` is set in `.env`
+- Verify the key is valid and has credits
+
+**Claude can't access files**
+
+- Check `CLAUDE_WORKING_DIR` points to an existing directory
+- Verify `ALLOWED_PATHS` includes directories you want Claude to access
+- Ensure the bot process has read/write permissions
+
+**MCP tools not working**
+
+- Verify `mcp-config.ts` exists and exports properly
+- Check that MCP server dependencies are installed
+- Look for MCP errors in the logs
+
+## License
+
+MIT