.env.example

# Claude Code Telegram Bot Configuration
#
# This bot provides remote access to Claude Code through Telegram with:
# - Terminal-like interface for Claude commands
# - File upload and archive extraction
# - Git repository integration
# - Quick action buttons for common tasks
# - Session export in multiple formats
# - Image/screenshot analysis
# - Smart follow-up suggestions

# === AUTHENTICATION SETUP ===
# Choose one of these Claude authentication methods:
#
# Option 1 (Recommended): Use existing Claude CLI authentication
# 1. Install Claude CLI: https://claude.ai/code
# 2. Login: claude auth login
# 3. Set USE_SDK=true (leave ANTHROPIC_API_KEY empty)
#
# Option 2: Direct API key
# 1. Get API key from: https://console.anthropic.com/
# 2. Set USE_SDK=true and ANTHROPIC_API_KEY=your-key
#
# Option 3: CLI subprocess mode (legacy)
# 1. Install and authenticate Claude CLI
# 2. Set USE_SDK=false

# === REQUIRED SETTINGS ===
# Telegram Bot Token from @BotFather
TELEGRAM_BOT_TOKEN=your_bot_token_here

# Bot username (without @)
TELEGRAM_BOT_USERNAME=your_bot_username

# Base directory for project access (absolute path)
APPROVED_DIRECTORY=/path/to/your/projects

# === SECURITY SETTINGS ===
# Comma-separated list of allowed Telegram user IDs (optional)
# Leave empty to allow all users (not recommended for production)
ALLOWED_USERS=123456789,987654321

# Enable token-based authentication
ENABLE_TOKEN_AUTH=false

# Secret for generating auth tokens (required if ENABLE_TOKEN_AUTH=true)
# Generate with: openssl rand -hex 32
AUTH_TOKEN_SECRET=

# Disable dangerous pattern validation in path/command checks (trusted env only)
# WARNING: enables characters like pipes and redirections in validated input
DISABLE_SECURITY_PATTERNS=false

# Disable Claude tool allowlist/disallowlist validation (trusted env only)
# WARNING: only bypasses tool-name allow/disallow checks; path/command safety checks still run
DISABLE_TOOL_VALIDATION=false

# === CLAUDE SETTINGS ===
# Integration method: Use Python SDK (true) or CLI subprocess (false)
USE_SDK=true

# Anthropic API key for SDK integration (optional if using CLI authentication)
# Get your API key from: https://console.anthropic.com/
ANTHROPIC_API_KEY=

# Path to Claude CLI executable (optional - will auto-detect if not specified)
# Example: /usr/local/bin/claude or ~/.nvm/versions/node/v20.19.2/bin/claude
CLAUDE_CLI_PATH=

# Maximum conversation turns before requiring new session
CLAUDE_MAX_TURNS=10

# Timeout for Claude operations (seconds)
CLAUDE_TIMEOUT_SECONDS=300

# Maximum cost per user in USD (lifetime budget for rate limiter)
CLAUDE_MAX_COST_PER_USER=10.0

# Maximum cost per individual request in USD (SDK-level hard cap)
CLAUDE_MAX_COST_PER_REQUEST=5.0

# Allowed Claude tools (comma-separated list)
CLAUDE_ALLOWED_TOOLS=Read,Write,Edit,Bash,Glob,Grep,LS,Task,TaskOutput,MultiEdit,NotebookRead,NotebookEdit,WebFetch,TodoRead,TodoWrite,WebSearch,Skill,AskUserQuestion,EnterPlanMode, ExitPlanMode

# === RATE LIMITING ===
# Number of requests allowed per window
RATE_LIMIT_REQUESTS=10

# Rate limit window in seconds
RATE_LIMIT_WINDOW=60

# Burst capacity for rate limiting
RATE_LIMIT_BURST=20

# === STORAGE SETTINGS ===
# Database URL (SQLite by default)
DATABASE_URL=sqlite:///data/bot.db

# Session timeout in hours
SESSION_TIMEOUT_HOURS=24

# Maximum concurrent sessions per user
MAX_SESSIONS_PER_USER=5

# === FEATURE FLAGS ===
# Enable Model Context Protocol
ENABLE_MCP=false

# Path to MCP configuration file
MCP_CONFIG_PATH=

# Enable Git integration (safe read-only git operations)
ENABLE_GIT_INTEGRATION=true

# Enable file upload handling (including archives)
ENABLE_FILE_UPLOADS=true

# Enable quick action buttons (context-aware actions)
ENABLE_QUICK_ACTIONS=true

# === ADVANCED FEATURE SETTINGS ===
# Maximum file upload size in MB (applies to archives too)
MAX_FILE_UPLOAD_SIZE_MB=100

# Maximum number of files to preview in archive analysis
MAX_ARCHIVE_PREVIEW_FILES=5

# Enable session export functionality (always enabled by default)
ENABLE_SESSION_EXPORT=true

# Enable image/screenshot handling
ENABLE_IMAGE_UPLOADS=true

# Enable conversation enhancements (follow-up suggestions)
ENABLE_CONVERSATION_MODE=true

# Quick actions timeout in seconds
QUICK_ACTIONS_TIMEOUT=120

# Git operations timeout in seconds
GIT_OPERATIONS_TIMEOUT=30

# === VOICE TRANSCRIPTION ===
# Enable voice message transcription
ENABLE_VOICE_MESSAGES=true

# Voice transcription provider: mistral, openai, or local
# - mistral: Uses Mistral Voxtral (requires MISTRAL_API_KEY)
# - openai: Uses OpenAI Whisper API (requires OPENAI_API_KEY)
# - local: Uses whisper.cpp binary (requires ffmpeg + whisper.cpp installed)
VOICE_PROVIDER=mistral

# API keys (only needed for cloud providers)
MISTRAL_API_KEY=
OPENAI_API_KEY=

# Override transcription model (optional)
# Defaults: voxtral-mini-latest (mistral), whisper-1 (openai), base (local)
VOICE_TRANSCRIPTION_MODEL=

# Maximum voice message size in MB
VOICE_MAX_FILE_SIZE_MB=20

# Local whisper.cpp settings (only used when VOICE_PROVIDER=local)
# Path to whisper.cpp binary (auto-detected from PATH if unset)
WHISPER_CPP_BINARY_PATH=
# Path to GGML model file, or model name like "base", "small", "medium"
# Named models look for ~/.cache/whisper-cpp/ggml-{name}.bin
WHISPER_CPP_MODEL_PATH=base

# === PROJECT THREAD MODE ===
# Enable strict routing by Telegram project topics
ENABLE_PROJECT_THREADS=false

# Thread mode:
# - private: topics inside private bot chat (primary)
# - group: forum topics in a supergroup
PROJECT_THREADS_MODE=private

# Target Telegram forum/supergroup chat ID (required only for PROJECT_THREADS_MODE=group)
# Example: -1001234567890
PROJECT_THREADS_CHAT_ID=

# Path to YAML project registry (see config/projects.example.yaml)
PROJECTS_CONFIG_PATH=

# Minimum delay (seconds) between Telegram API calls during topic sync
# Set 0 to disable pacing
PROJECT_THREADS_SYNC_ACTION_INTERVAL_SECONDS=1.1

# === MONITORING ===
# Log level (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

# Enable anonymous telemetry
ENABLE_TELEMETRY=false

# Sentry DSN for error tracking (optional)
SENTRY_DSN=

# === DEVELOPMENT ===
# Environment (development, testing, production)
ENVIRONMENT=development

# Enable debug mode
DEBUG=false

# Enable development features
DEVELOPMENT_MODE=true