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 |
|---|---|---|
| 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 |
ANTHROPIC_API_KEY is optional if using a Claude Max subscription with claude CLI configured.
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.
Real-Time Streaming
Watch Claude's responses appear character by character. No waiting โ see progress as it happens with debounced updates.
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 using OpenAI TTS with 13 voices. Toggle with /tts command.
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.
Telegraph Output
Export long responses to Telegraph for better readability with /telegraph command.
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.
Teleport to Terminal
Move your conversation from Telegram to a terminal session with /teleport. Fork and continue in both places.
Terminal UI Mode
Terminal-style display with animated spinners, tool status indicators, and progress updates. Toggle with /terminalui.
Architecture
How It Works
Reference
Commands
Project Management
/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
/model
Switch Claude model (opus/sonnet/haiku)
/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
Export last response to Telegraph
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
/botstatus
Show bot process status
/restartbot
Restart the bot process
