A direct Telegram interface to Claude Code CLI with intelligent output filtering and seamless chat integration.
- Direct Claude Code Access: All messages route directly to Claude Code CLI (no OpenRouter routing)
- Intelligent Output Cleaning: LLM-powered filtering removes noise and formats output for mobile chat
- PTY Session Management: Full terminal emulation supporting Claude Code's interactive features
- File Upload Integration: Upload files via Telegram and access them in Claude Code sessions
- Session Persistence: Conversations persist across Claude Code restarts with context preservation
- Modular Architecture: Clean, maintainable codebase with separated utility components
User Message → MessageHandler → ClaudeCodeManager (PTY) → Claude Code CLI
↓
User ← OutputCleanerService (LLM) ← SessionManager ← Claude Code Output
openrouter-claude-bot/
├── src/
│ ├── managers/
│ │ ├── ClaudeCodeManager.js # Claude CLI orchestration via PTY
│ │ └── SessionManager.js # Session & conversation tracking
│ ├── handlers/
│ │ ├── MessageHandler.js # Telegram message routing
│ │ └── CallbackHandler.js # Inline keyboard handling
│ ├── services/
│ │ └── OutputCleanerService.js # LLM-based output filtering
│ ├── utils/
│ │ ├── ClaudeAuthenticator.js # Claude Code authentication
│ │ ├── PTYSessionHandler.js # PTY process management
│ │ ├── OutputDetector.js # Processing state detection
│ │ ├── fileManager.js # File upload handling
│ │ └── logger.js # Winston logging
│ └── OpenRouterClaudeBot.js # Main bot orchestrator
├── config/
│ └── config.js # Configuration management
├── telegram-uploads/ # User uploaded files (auto-created)
├── index.js # Entry point
└── package.json
-
Clone and Setup:
cd openrouter-claude-bot npm install -
Install Claude Code CLI:
npm install -g @anthropic-ai/claude-code
-
Environment Configuration:
cp .env.example .env # Edit .env with your credentials -
Create Logs Directory:
mkdir logs
TELEGRAM_BOT_TOKEN: Your Telegram bot token from @BotFather
OPENROUTER_API_KEY: OpenRouter API key for LLM-based output cleaning (recommended)TELEGRAM_AUTHORIZED_CHATS: Comma-separated chat IDs for access control (leave empty for public access)CLAUDE_INIT_TIMEOUT: Claude Code initialization timeout in seconds (default: 30)
-
Start the Bot:
npm start
-
Development Mode:
npm run dev
-
Telegram Commands:
/start- Welcome message and help/new- Start fresh conversation (clears session and history)/status- Bot and session status/files- List uploaded files/delete <filename>- Delete specific file/cleanup- Delete all files with confirmation/restart- Restart Claude Code agent/interrupt- Send ESC key to interrupt processing/cancel- Cancel active sessions
- User sends message → Directly routed to Claude Code CLI via PTY
- Claude Code processes → Full interactive terminal session with all features
- Output generated → Buffered and detected using ⏺ symbol pattern
- LLM cleaning → OutputCleanerService filters noise using conversation context
- Cleaned output → Delivered to user via Telegram with proper formatting
- Orchestrates Claude CLI interactions using PTY sessions
- Manages agent lifecycle and intelligent output detection
- Handles authentication and command routing
- Uses modular utility components (ClaudeAuthenticator, PTYSessionHandler, OutputDetector)
- Tracks Claude Code sessions and conversation history
- Manages file uploads and storage per chat
- Provides session statistics and cleanup
- Maintains conversation context for LLM cleaning
- Uses LLM (Gemini 2.5 Flash) to intelligently filter Claude Code output
- Removes noise, ANSI codes, progress indicators, and duplicate content
- Formats output for mobile chat consumption
- Considers conversation context for better cleaning decisions
- Routes all Telegram messages directly to Claude Code
- Handles file uploads and command processing
- Manages user responses to Claude Code questions
- Coordinates output cleaning and delivery
- ClaudeAuthenticator: Handles Claude Code CLI authentication flow
- PTYSessionHandler: Manages PTY process creation and communication
- OutputDetector: Detects Claude Code processing state and completion patterns
- FileManager: Handles file uploads to
./telegram-uploads/chat_<id>/
Logs are written to both console and file (logs/openrouter-claude-bot.log). Log level can be configured via LOG_LEVEL environment variable.
- Uses
node-ptyfor full terminal emulation - Supports interactive prompts and questions
- Handles ANSI codes and escape sequences
- Real-time output streaming with intelligent buffering
- Buffer Management: Collects Claude output in chunks
- Smart Detection: Identifies when Claude is waiting vs. still processing using ⏺ symbol
- LLM Cleaning: Filters noise, combines related outputs, formats for mobile
- Telegram Delivery: Handles message chunking and formatting
- Context Preservation: Sessions persist even when Claude Code exits
- Automatic Restart: Completed sessions automatically restart when user sends new messages
- One session per chat: New Claude sessions automatically terminate existing ones
- File Integration: Uploaded files are saved to
./telegram-uploads/chat_<id>/and made available to Claude
- Graceful shutdown with cleanup of all Claude processes
- Automatic session recovery with context preservation
- Comprehensive error logging with Winston
- Modular error handling in separate utility components
- Follow the existing modular architecture
- Add proper error handling and logging
- Update documentation for new features
- Test with various Telegram scenarios
Apache License 2.0 - see LICENSE file for details.
This project is licensed under the Apache License 2.0, which allows for commercial use, modification, and distribution while requiring attribution to the original work. See the NOTICE file for attribution requirements.