Claude Code
via Telegram
Your personal AI agent, running on your machine, controlled from Telegram.
Installation
Getting Started
Prerequisites
caffeinate to prevent sleep during long operations.
Quick Start
git clone https://github.com/nachoSEO/claudegram.git cd claudegram npm install cp .env.example .env # Edit .env with your credentials npm run dev
Step-by-Step Setup
Clone the repository
Download the project using git clone
Install dependencies
Run npm install in the project directory
Create Telegram bot
Message @BotFather on Telegram and use /newbot to get your token
Get your Telegram user ID
Message @userinfobot on Telegram to get your numeric user ID
Configure environment
Copy .env.example to .env and fill in your credentials
Run the bot
Start with npm run dev for development or npm start for production
Verify it works
Send a message to your bot on Telegram and check for a response
Configuration
| Variable | Description | Required |
|---|---|---|
| Core | ||
| TELEGRAM_BOT_TOKEN | Bot token from BotFather | Yes |
| ALLOWED_USER_IDS | Comma-separated Telegram user IDs | Yes |
| ANTHROPIC_API_KEY | Your Anthropic API key | Optional* |
| WORKSPACE_DIR | Default workspace path for projects | No |
| STREAMING_MODE | streaming or wait for responses |
No |
| BOT_MODE | dev or prod |
No |
| DANGEROUS_MODE | Auto-approve all tool permissions (default: false) | No |
| API Keys | ||
| OPENAI_API_KEY | For OpenAI TTS voices | For TTS |
| GROQ_API_KEY | For voice transcription & Orpheus TTS | For voice |
| REDDIT_CLIENT_ID | Reddit OAuth2 app client ID | For Reddit |
| REDDIT_CLIENT_SECRET | Reddit OAuth2 app client secret | For Reddit |
| REDDIT_USERNAME | Reddit bot account username | For Reddit |
| REDDIT_PASSWORD | Reddit bot account password | For Reddit |
| Feature Flags | ||
| TTS_ENABLED | Enable text-to-speech (default: true) | No |
| REDDIT_ENABLED | Enable /reddit command (default: true) | No |
| VREDDIT_ENABLED | Enable /vreddit command (default: true) | No |
| MEDIUM_ENABLED | Enable /medium command (default: true) | No |
| TRANSCRIBE_ENABLED | Enable voice transcription (default: true) | No |
| EXTRACT_ENABLED | Enable /extract command (default: true) | No |
| TTS Configuration | ||
| TTS_PROVIDER | openai or groq (default: groq) |
No |
| TTS_VOICE | Default voice name (default: coral) | No |
| TTS_SPEED | Playback speed multiplier (default: 1.0) | No |
| Display & Behavior | ||
| TERMINAL_UI_DEFAULT | Terminal-style display on by default (default: true) | No |
| MAX_LOOP_ITERATIONS | Max iterations for /loop mode (default: 5) | No |
| CANCEL_ON_NEW_MESSAGE | Auto-cancel running query on new message (default: false) | No |
ANTHROPIC_API_KEY is optional if using a Claude Max subscription with claude CLI configured. All feature flags default to true — disabled features auto-hide from the Telegram menu.
Capabilities
Full Agent Power in Your Pocket
Mobile-First
Send coding requests from anywhere using Telegram. Perfect for quick fixes, code reviews, or managing projects on the go.
Smart Streaming
See what Claude is doing in real time — tool status updates show current operations. Complete response delivered when done, avoiding rate limits.
Full Tool Access
Read files, write code, run bash commands, search codebases. Every Claude Code capability available through chat.
Security Hardened
SSRF protection blocks private networks, workspace boundaries prevent path traversal, and restrictive file permissions protect your data.
Feature Flags
Enable or disable optional features via environment variables. Commands auto-hide from Telegram menu when disabled.
Voice Transcription
Send voice messages and have them transcribed with Groq Whisper. Just talk to Claude instead of typing.
Text-to-Speech
Get Claude's responses as voice messages. 13 OpenAI voices + 6 Groq Orpheus voices with configurable speed and autoplay.
Media Extraction
Download videos from YouTube, TikTok, Instagram with /extract. Auto-detects URLs in messages.
Native Reddit Module
Pure TypeScript Reddit integration with OAuth2. Interactive mode picker (File/Chat/Both) for flexible content delivery.
Medium Reader
Read Medium articles without paywalls using /medium. Full article content delivered to chat.
Image Vision
Send photos directly in chat. Images are sent as multimodal vision input — Claude sees the actual image for accurate analysis, descriptions, and edits.
Telegraph Output
Long responses auto-render as Telegraph articles with Instant View. Toggle on/off per chat with /telegraph.
Session Persistence
Resume conversations across bot restarts with /resume and /continue. Browse history with /sessions.
Model Picker
Switch between Claude models (Opus, Sonnet, Haiku) with /model. Default: Opus for best results.
Provider Switching
Switch between Claude and OpenCode with /provider. Access 75+ LLM providers when Claude is unavailable.
Teleport to Terminal
Move your conversation from Telegram to a terminal session with /teleport. Fork and continue in both places.
Forum Topic Sessions
Each forum topic in a Telegram group runs as an independent session. Work on multiple projects in parallel across different topics.
Terminal UI Mode
Terminal-style display with tool status indicators showing what Claude is doing. Updates only on tool changes to stay within rate limits. Toggle with /terminalui.
Completion Notifications
Get a push notification when long-running tasks finish. Configurable threshold (default: 60s) — never miss a completed task again.
Proxy Support
Connect through HTTP/HTTPS/SOCKS proxies via TELEGRAM_PROXY_URL or standard HTTP_PROXY env vars. Essential for restricted networks.
Intelligent Routing
Talk naturally — Claude automatically uses the right tools for Reddit, Medium, YouTube, and project management without explicit commands.
Architecture
How It Works
Reference
Commands
Project Management
/start
Welcome message and getting started guide
/project <name>
Open a project from your workspace directory
/newproject <name>
Create and open a new project
/clear
Clear the current session and start fresh
/status
Show current session and project info
Session Management
/resume
Resume the last session for current project
/continue
Continue last session after bot restart
/sessions
Browse and restore previous sessions
/teleport
Move session to terminal (forked)
Agent Modes
/provider
Switch AI provider (Claude / OpenCode)
/model
Switch AI model (provider-aware)
/mode
Toggle streaming vs wait response mode
/terminalui
Toggle terminal-style display with spinners
/plan
Enter plan mode for architecture discussions
/explore
Enter explore mode for codebase analysis
/loop
Toggle loop mode for continuous tasks
Media & Content
/extract <url>
Download media from YouTube, TikTok, Instagram
/reddit <sub>
Browse subreddit posts
/vreddit <url>
Download Reddit videos with audio
/medium <url>
Read Medium articles without paywall
/file <path>
Get a project file as Telegram download
/telegraph
Toggle Instant View for long responses, or view a file
Voice & Audio
/tts
Toggle text-to-speech for responses
/transcribe
Transcribe audio without sending to agent
Utility
/context
Show current context window usage
/cancel
Cancel current request
/softreset
Soft reset (cancel + clear session)
/commands
Show all available commands
/ping
Health check (bypasses processing queue)
/botstatus
Show bot process status
/restartbot
Restart the bot process
