.env.example

# =============================================================================
# Claude Code Telegram Bot v2.0.0 - Environment Configuration
# =============================================================================
# Copy this file to .env and fill in required values.
# Lines starting with # are comments. Remove # to enable a setting.
# =============================================================================

# === 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. Leave ANTHROPIC_API_KEY empty
#
# Option 2: Direct API key
#   1. Get API key from: https://console.anthropic.com/
#   2. Set ANTHROPIC_API_KEY=your-key

# =============================================================================
# REQUIRED SETTINGS
# These must be set for the bot to start.
# =============================================================================

# Telegram bot token from @BotFather (REQUIRED)
TELEGRAM_BOT_TOKEN=your-telegram-bot-token

# Bot username without the @ prefix (REQUIRED)
TELEGRAM_BOT_USERNAME=your_bot_username

# Base directory for project access - must exist and be absolute (REQUIRED)
APPROVED_DIRECTORY=/path/to/your/projects

# Comma-separated Telegram user IDs allowed to use the bot (REQUIRED for security)
# Leave unset to allow all users (NOT recommended for production)
# ALLOWED_USERS=123456789,987654321

# =============================================================================
# CLAUDE / ANTHROPIC SETTINGS
# =============================================================================

# Anthropic API key (optional if Claude CLI is already logged in)
# ANTHROPIC_API_KEY=sk-ant-...

# Path to Claude CLI executable (auto-detected if unset)
# CLAUDE_CLI_PATH=/usr/local/bin/claude

# Claude model to use (defaults to CLI default if unset)
# CLAUDE_MODEL=claude-sonnet-4-20250514

# Maximum conversation turns per request
CLAUDE_MAX_TURNS=10

# Timeout in seconds for Claude operations
CLAUDE_TIMEOUT_SECONDS=300

# Maximum cost (USD) per user across all requests
CLAUDE_MAX_COST_PER_USER=10.0

# Maximum cost (USD) per individual request (SDK budget cap)
CLAUDE_MAX_COST_PER_REQUEST=5.0

# Comma-separated list of allowed Claude tools
CLAUDE_ALLOWED_TOOLS=Read,Write,Edit,Bash,Glob,Grep,LS,Task,TaskOutput,MultiEdit,NotebookRead,NotebookEdit,WebFetch,TodoRead,TodoWrite,WebSearch,Skill

# Comma-separated list of explicitly disallowed tools/commands
# CLAUDE_DISALLOWED_TOOLS=

# =============================================================================
# FEATURE FLAGS
# =============================================================================

# Conversational agentic mode (true) vs classic command mode (false)
AGENTIC_MODE=true

# Enable FastAPI webhook/API server
ENABLE_API_SERVER=false

# Enable APScheduler job scheduler
ENABLE_SCHEDULER=false

# Enable Model Context Protocol
ENABLE_MCP=false
# MCP_CONFIG_PATH=/path/to/mcp-config.json

# Enable git integration commands
ENABLE_GIT_INTEGRATION=true

# Enable file upload handling
ENABLE_FILE_UPLOADS=true

# Enable voice message transcription
ENABLE_VOICE_MESSAGES=true

# Voice transcription provider: "mistral" or "openai"
VOICE_PROVIDER=mistral
# MISTRAL_API_KEY=your-mistral-key
# OPENAI_API_KEY=your-openai-key
# VOICE_TRANSCRIPTION_MODEL=voxtral-mini-latest
VOICE_MAX_FILE_SIZE_MB=20

# Enable quick action buttons
ENABLE_QUICK_ACTIONS=true

# Enable strict routing by Telegram forum project threads
ENABLE_PROJECT_THREADS=false
# PROJECT_THREADS_MODE=private
# PROJECT_THREADS_CHAT_ID=
# PROJECTS_CONFIG_PATH=
# PROJECT_THREADS_SYNC_ACTION_INTERVAL_SECONDS=1.1

# Quote the original message when replying
REPLY_QUOTE=true

# Output verbosity: 0=quiet, 1=normal, 2=detailed
VERBOSE_LEVEL=1

# Stream partial responses via Telegram sendMessageDraft
ENABLE_STREAM_DRAFTS=false
STREAM_DRAFT_INTERVAL=0.3

# =============================================================================
# NEW: INTERNATIONALIZATION (i18n)
# =============================================================================

# Default language for user-facing messages: "en" (English) or "zh" (Chinese)
DEFAULT_LANGUAGE=en

# Comma-separated list of supported language codes
SUPPORTED_LANGUAGES=en,zh

# =============================================================================
# NEW: PLUGIN SYSTEM
# =============================================================================

# Enable the plugin system
ENABLE_PLUGINS=false

# Directory to scan for plugin modules
# PLUGINS_DIRECTORY=/path/to/plugins

# Comma-separated list of plugin names to enable (empty = all discovered plugins)
# ENABLED_PLUGINS=

# =============================================================================
# NEW: CACHE LAYER (memory + Redis)
# =============================================================================

# Enable the cache layer
ENABLE_CACHE=false

# Cache backend: "memory" (in-process) or "redis" (distributed)
CACHE_BACKEND=memory

# Redis URL (required when CACHE_BACKEND=redis)
# REDIS_URL=redis://localhost:6379

# Default cache TTL in seconds
CACHE_DEFAULT_TTL=300

# Maximum entries for in-memory cache
CACHE_MAX_SIZE=1000

# =============================================================================
# NEW: WEB DASHBOARD
# =============================================================================

# Enable web dashboard at /dashboard
ENABLE_DASHBOARD=false

# Dashboard basic auth credentials (recommended when dashboard is enabled)
# DASHBOARD_USERNAME=admin
# DASHBOARD_PASSWORD=changeme

# =============================================================================
# NEW: ALERT MECHANISM
# =============================================================================

# Cost threshold per user (USD) before alert fires
ALERT_COST_THRESHOLD_PER_USER=10.0

# Global aggregate cost threshold (USD) before alert fires
ALERT_COST_THRESHOLD_GLOBAL=100.0

# Number of errors in 5 minutes to trigger an alert
ALERT_ERROR_RATE_THRESHOLD=10

# Comma-separated Telegram chat IDs to receive alert notifications
# ALERT_ADMIN_CHAT_IDS=123456789

# Minimum seconds between repeated alerts of the same type
ALERT_COOLDOWN_SECONDS=3600

# =============================================================================
# NEW: METRICS & OBSERVABILITY (Prometheus + Grafana)
# =============================================================================

# Enable /metrics endpoint (Prometheus format)
ENABLE_METRICS=false

# Log output format: "console" (human-readable) or "json" (structured)
LOG_FORMAT=json

# =============================================================================
# NEW: DATABASE (SQLite default, PostgreSQL optional)
# =============================================================================

# Database connection URL
# SQLite (default):  sqlite:///data/bot.db
# PostgreSQL:        postgresql://user:pass@localhost:5432/botdb
DATABASE_URL=sqlite:///data/bot.db

# PostgreSQL connection pool settings (only used with PostgreSQL)
DB_POOL_MIN_SIZE=2
DB_POOL_MAX_SIZE=10

# =============================================================================
# NEW: GRACEFUL DEGRADATION (circuit breaker + retry + queue)
# =============================================================================

# Enable circuit breaker and request queuing
ENABLE_GRACEFUL_DEGRADATION=true

# Consecutive failures before circuit opens
CIRCUIT_BREAKER_THRESHOLD=5

# Seconds before circuit transitions from open to half-open
CIRCUIT_BREAKER_COOLDOWN_SECONDS=60

# Maximum pending requests when circuit is open
MAX_QUEUED_REQUESTS=100

# Maximum retry attempts for transient errors
RETRY_MAX_ATTEMPTS=3

# =============================================================================
# NEW: CODE REVIEW (/review + auto PR review)
# =============================================================================

# Enable automated code review feature (/review command)
ENABLE_CODE_REVIEW=false

# Automatically review PRs/MRs received from webhooks
CODE_REVIEW_AUTO=false

# GitHub API token for fetching PR diffs and posting review comments
# GITHUB_API_TOKEN=ghp_...

# =============================================================================
# NEW: WEBHOOKS (GitHub + GitLab + Bitbucket)
# =============================================================================

# GitHub webhook HMAC secret
# GITHUB_WEBHOOK_SECRET=your-github-secret

# GitLab webhook secret token
# GITLAB_WEBHOOK_SECRET=your-gitlab-secret

# Bitbucket webhook HMAC secret
# BITBUCKET_WEBHOOK_SECRET=your-bitbucket-secret

# Generic webhook shared secret
# WEBHOOK_API_SECRET=your-generic-secret

# Comma-separated Telegram chat IDs for proactive notifications
# NOTIFICATION_CHAT_IDS=123456789

# =============================================================================
# NEW: INTERACTIVE CONFIRMATION (dangerous operation prompts)
# =============================================================================

# Prompt user before executing dangerous operations
ENABLE_CONFIRMATIONS=true

# Seconds before a confirmation request expires (10-300)
CONFIRMATION_TIMEOUT_SECONDS=60

# Additional regex patterns to flag as dangerous (comma-separated)
# DANGEROUS_PATTERNS=

# =============================================================================
# SECURITY
# =============================================================================

# Rate limiting
RATE_LIMIT_REQUESTS=10
RATE_LIMIT_WINDOW=60
RATE_LIMIT_BURST=20

# Token-based authentication
ENABLE_TOKEN_AUTH=false
# AUTH_TOKEN_SECRET=your-secret-key

# Disable dangerous pattern validation (pipes, redirections, etc.)
# WARNING: only enable in trusted environments!
DISABLE_SECURITY_PATTERNS=false

# Allow all Claude tools by bypassing tool validation
# WARNING: only bypasses tool-name checks; path/command safety checks still run
DISABLE_TOOL_VALIDATION=false

# OS-level bash sandboxing for approved directory
SANDBOX_ENABLED=true
# SANDBOX_EXCLUDED_COMMANDS=git,npm,pip,poetry,make,docker

# Session settings
SESSION_TIMEOUT_HOURS=24
SESSION_TIMEOUT_MINUTES=120
MAX_SESSIONS_PER_USER=5

# =============================================================================
# MONITORING & DEBUGGING
# =============================================================================

# Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_LEVEL=INFO

# Enable anonymous telemetry
ENABLE_TELEMETRY=false

# Sentry DSN for error tracking
# SENTRY_DSN=https://...@sentry.io/...

# Enable debug mode
DEBUG=false

# Enable development features
DEVELOPMENT_MODE=false

# =============================================================================
# WEBHOOK SERVER (Telegram webhook mode, alternative to polling)
# =============================================================================

# WEBHOOK_URL=https://your-domain.com
WEBHOOK_PORT=8443
WEBHOOK_PATH=/webhook

# API server port (for FastAPI webhook/API server)
API_SERVER_PORT=8080

# =============================================================================
# A2A (Agent-to-Agent) PROTOCOL
# =============================================================================

# Enable A2A protocol server and client
ENABLE_A2A=false
# A2A_AGENT_NAME=claude-code-telegram
# A2A_AGENT_DESCRIPTION=Claude Code agent accessible via Telegram
# A2A_AGENT_URL=https://your-domain.com
# A2A_API_TOKEN=your-a2a-bearer-token