How richardatct/claude-code-telegram works
Claude Code Telegram Bot provides conversational and classic-mode access to project work, with per-user/project session continuity. Telegram updates enter the orchestrator and reach Claude for agentic responses; classic commands add project navigation and feature actions. A parallel automation path accepts webhooks and scheduled triggers through a typed event bus, with notifications delivering results. SQLite supports sessions, usage and automation state, while configuration and security checks constrain operation. The README documents feature breadth; unsampled modules and runtime wiring are represented only where tree/index or README evidence supports them.
Main entry points: orchestrator.py Update orchestrator · bus.py Event bus · main.py Application startup · handlers.py Event handlers
Components 21
Telegram interaction
- Update orchestrator
src/bot/orchestrator.py - Classic handlers
src/bot/handlers - Bot features
src/bot/features - Project threads
src/projects/thread_manager.py
Claude execution
- Claude facade
src/claude/facade.py - Claude SDK
src/claude/sdk_integration.py - Session manager
src/claude/session.py - Response formatting
src/bot/utils/formatting.py
Event automation
- Webhook API
src/api/server.py - Job scheduler
src/scheduler/scheduler.py - Event bus
src/events/bus.py - Event handlers
src/events/handlers.py - Notifications
src/notifications/service.py
Security and configuration
- Settings
src/config/settings.py - Security controls
src/security - Application startup
src/main.py
Persistence
- SQLite storage
src/storage/database.py - Data repositories
src/storage/repositories.py - Session persistence
src/storage/session_storage.py
Other components
- Telegram user
- Webhook or schedule
Connections 23
- Telegram user → Update orchestrator: sends updates
README.md - Update orchestrator → Classic handlers: routes classic mode
src/bot/orchestrator.py - Update orchestrator → Claude SDK: runs agentic requests
src/bot/orchestrator.py - Update orchestrator → Project threads: syncs topics
src/bot/orchestrator.py - Classic handlers → Bot features: offers actions
README.md - Claude facade → Claude SDK: delegates execution
src/claude/facade.py - Claude facade → Session manager: manages sessions
src/claude/facade.py - Update orchestrator → Response formatting: formats replies
src/bot/orchestrator.py - Webhook or schedule → Webhook API: sends webhook
README.md - Webhook API → Event bus: publishes events
src/api/server.py - Job scheduler → Event bus: publishes triggers
src/scheduler/scheduler.py - Event bus → Event handlers: dispatches events
src/events/bus.py - Event handlers → Claude facade: requests agent work
src/events/handlers.py - Event handlers → Notifications: routes responses
- Notifications → Telegram user: delivers results
README.md - Application startup → Settings: loads configuration
src/main.py - Application startup → Event bus: starts runtime bus
src/main.py - Application startup → Job scheduler: configures jobs
README.md - Claude SDK → Security controls: validates tool paths
src/claude/sdk_integration.py - Session manager → Session persistence: persists sessions
src/claude/session.py - Session persistence → SQLite storage: uses database connections
src/storage/session_storage.py - Data repositories → SQLite storage: uses database connections
src/storage/repositories.py - Project threads → Data repositories: reads thread mappings
src/projects/thread_manager.py