Claude Code
from Telegram
A full coding agent on your own machine, driven from your phone. It keeps working while you're away, pages you when it's done, and falls back to another provider when your usage limit runs out.
Why TeleCoder
Built to keep going
Survives your usage limit
When Claude Max throttles mid-turn, TeleCoder doesn't just report the
error — it offers a one-tap switch to Claude Code Router and replays the
message you just sent. A provider router sits behind every message, so
Claude, CCR and OpenCode are all reachable from /provider.
Two transports, one agent
Run against the Claude Agent SDK, or drive the real claude
CLI in a pseudo-terminal with /method — built for the policy
split between programmatic usage and a Pro/Max subscription. Session
resume, forks and /compact work either way.
It pages you
Long tasks run in the background and ping you when they finish; short ones edit their own message in place so the chat stays quiet. Monitor output, subagent lifecycle and plan mode all surface as they happen instead of arriving in one wall of text at the end.
Many bots, one process
A multi-instance launcher runs several bots side by side with per-bot session scoping, each with its own project, model and reasoning effort — and a watchdog that notices when a query hangs instead of leaving you staring at a silent chat.
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, with rotating thinking verbs for personality. Complete response delivered when done, avoiding rate limits.
Live Tips
The same contextual tips Claude Code shows in the terminal appear under the status indicator while it works — scraped live from the CLI and mirrored into your chat (PTY mode).
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.
Update Notifications
Spots Claude Code's "Update available" or auto-update banner at PTY startup and forwards the notice to Telegram — so you know when to upgrade.
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.
Smart Table Rendering
Markdown tables are auto-rewritten as bold-labeled records, since Telegram has no monospace table layout. Each row becomes a clean key-value block instead of garbled pipe text.
Session Persistence
Sessions auto-restore after any restart (planned, crash, or cold start). Recent sessions (under an hour) are silently reattached so your next message just continues. Sessions idle between 1h and 7d get a "Continue or start fresh?" prompt. Older sessions stay parked behind /resume and /continue.
Predicted Next Prompt
Opt in with /suggestions to scrape Claude Code's ghost-text prompt suggestion from the TUI at end-of-turn and surface it as an inline button under each response. Tap to send it as your next message. Free — the suggestion piggybacks on Claude Code's own speculation, no extra API call.
Hot Reload
Rebuild and restart the bot with /rebuildbot. Sessions are automatically restored — no manual button clicks needed.
Model Picker
Switch between Claude models (Opus, Sonnet, Haiku) with /model. Default: Opus for best results.
Skills Support
Claude can invoke project-level skills from .claude/skills/ via the Skill tool. User-level skills load when CLAUDE_SDK_LOAD_USER_SETTINGS=true.
Todo Tracking
Claude can plan multi-step work with the TodoWrite tool, posting and updating a checklist as it progresses.
Ask User
Claude can pop up a Telegram inline keyboard with multiple-choice options when it needs a clear decision, along with any comparison or rationale you need to choose. Tap a button to answer; the agent loop continues with your choice.
Provider Switching
Switch between Claude, CCR, and OpenCode with /provider. Access 75+ LLM providers when Claude is unavailable. Switching a live conversation confirms first, then starts a fresh session on the new backend with a plain-text summary of the prior chat carried over — backends can't share a session (a different model's thinking blocks can't be replayed), so each is kept cleanly separate.
PTY Mode (Subscription Path)
Switch with /method to drive Claude Code as an interactive pseudo-terminal session instead of the Agent SDK. Built for the 2026-06-15 policy split that separates programmatic-pool usage from Pro/Max subscription. Verbose UI (tool indicators, edit diffs, action log) is delivered via hook events from the spawned claude; reddit / medium / telegraph / set_topic are available as MCP tools loaded from a standalone subprocess. SDK mode remains available as a fallback.
Max Throttle Fallback
When the Claude Max usage limit hits, the bot detects it and offers a one-tap switch to Claude Code Router (CCR) — your message replays automatically through your chosen alt provider.
Project Favorites
/project opens with your favorite projects — one tap to switch. ⭐ from inside the workspace browser to add the current folder, or use ✍️ Enter path to point at any directory on disk (escapes the workspace root). Favorites persist across restarts in ~/.claudegram/project-favorites.json.
Side Questions
/btw answers a question about the running task without interrupting it. SDK mode asks the live query directly; PTY mode forks the session into a read-only, non-persisted copy that sees the transcript up to the current moment — the working turn never pauses and the transcript is never written to. One labelled message shows live progress while the side question works, then collapses to a receipt (“3 tools · 22s”) with the answer below it.
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.
Per-Turn Status Line
Sends a small status line after each turn showing the current topic, effort, model, context %, and cost — right above the compose box and visible in the Telegram chat list as the latest message. Active counters (🔄 backgrounded tasks, 📡 monitors, 🔍 PTY bg shells) appear only when non-zero so quiet turns stay quiet. Optional sub-toggles for your last prompt (handy under verbose mode, where the action log can bury what you typed) and a copy-pasteable claude --resume <id> line for CLI fallback. Off by default; opt in with /statusline.
Completion Notifications
Get a push notification when long-running tasks finish. Configurable threshold (default: 60s) — never miss a completed task again.
Verbosity Tiers
One per-chat setting (quiet / normal / verbose / debug) drives how much detail TeleCoder surfaces each turn. Verbose adds the per-turn usage footer, untruncated tool inputs, and a consolidated action log that streams tool results and diffs live in a single updatable message, then collapses to a Telegraph link at the end of the turn so the chat history stays tidy. Debug extends the action log with longer previews (40 lines vs 20). Quiet drops the completion ping. Set with /verbosity; env-level default via VERBOSITY_DEFAULT.
Back to Previous Session
After /clear, /project, /newproject, or /start, TeleCoder appends a one-tap inline button that resumes the most recent prior session — handy if you regret a clear or want to jump back to the project you just left.
Session Recap
Use /recap [N] to re-read the last N user/assistant exchanges from the active session (default 3). After /resume or /continue, TeleCoder drops a one-line tip pointing at the command so you can quickly orient yourself in a restored session.
Missed-Reply Catch-up
After every turn, TeleCoder cross-checks what it sent against Claude Code's canonical session log and auto-posts anything the extractor missed (pure tool-call turns, multi-block lossy screen-scrape, early end-of-turn flushes). Hit /sync any time to manually re-check — bypasses the queue so it works during hung turns.
Conversation Forks
Every assistant message gets a 🍴 Fork button that branches the conversation up to that point. Pick "New branch here" to fork into a fresh conversation on the same bot — your current thread is saved to /resume history and you continue from the branch point. Or pick a sibling bot from your multi-bot setup to hand it off: open that bot and your next message triggers an accept/decline prompt (accepting loads the truncated transcript, its prior conversation stays in /resume history). Either way you explore a different angle without losing the original.
Scheduled Tasks
Use /schedule to run a prompt on a recurring cadence. Supports intervals (every 5m, every 1h) and cron-style days/times (daily 9am, weekdays 14:00, mon,wed,fri 10:30). Each fire posts a "🔔 Scheduled" header and runs through the same session as your manual chats. Hard caps (10 active per chat, 50 fires default) keep runaway API spend in check.
Claude Self-Scheduling
In PTY mode, Claude has access to claudegram_loop and claudegram_schedule MCP tools so it can set up its own recurring tasks ("ping me when CI finishes", "remind me about this tomorrow"). Built-in CronCreate / ScheduleWakeup are blocked since they can't reach back into Telegram — set CLAUDEGRAM_ALLOW_NATIVE_SCHEDULING=1 to re-enable for experimentation.
Async Event Relay
In PTY mode, TeleCoder surfaces task-notifications from Monitor, Bash(run_in_background=true), and Task subagents to Telegram between turns. Each event posts as a "📡 Monitor — ...", "⚙️ Backgrounded: ...", or "🤖 Subagent started: ..." header, with the raw event payload (▸ trigger line) and Claude's analysis. When a backgrounded task or subagent finishes, the original "started" message is edited in place to "✅ Backgrounded: ... (12s)" so the chat doesn't stay stuck on a stale "in progress" line — short tasks edit silently, longer ones (≥ NOTIFICATION_THRESHOLD_SECONDS) and failures also post a fresh message so Telegram pings you. PushNotification is also relayed as "🔔 <message>". Useful for "tail this log and tell me when it errors", "build the docs in the background", or "delegate Y to a subagent" tasks.
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.
File Delivery
Claude proactively sends generated files (SVGs, images, reports) directly to your Telegram chat. No manual download needed.
Auto-Topic
Claude automatically updates the conversation topic in the status line to reflect the current work. Shows what you're working on at a glance.
Background Tasks
Long-running subagents run in the background while Claude keeps responding. A compact counter shows how many tasks are active. When a task finishes, the original "started" message is edited in place to show the status and duration; tasks that ran longer than NOTIFICATION_THRESHOLD_SECONDS (default 60s) or that errored also post a fresh notification so Telegram pings you.
Monitor Streams
Claude can subscribe to streaming output (log tails, file watches, CI checks). Each event arrives as a separate Telegram message so you can react in real time.
Background Process Reaper
/shells lists the actual OS-level shells the PTY claude session has spawned — every Bash(run_in_background=true) poller and Monitor loop, with cmdline and age. One tap SIGTERMs the chosen process plus its descendants, rescuing sessions whose watcher will never fire.
Installation
Getting Started
Prerequisites
caffeinate to prevent sleep during long operations.
Quick Start
git clone https://github.com/gitaarik/telecoder.git cd telecoder 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.
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 [-y]
Clear conversation history (project stays selected); pass -y to skip the confirmation prompt
/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
/recap [N]
Re-read the last N exchanges of the current session (default 3)
/sync
Resend the latest assistant reply from the session log if Telegram missed any of it
/fork
Fork the current conversation — into a new branch on this same bot, or hand it off to a sibling bot (alternative to tapping the 🍴 Fork button on a past assistant message)
/accept
Accept a pending fork from another bot — loads the forked transcript into this bot (your current conversation stays in /resume history)
/decline
Discard a pending fork from another bot without loading it
/schedule <when> <prompt>
Schedule a recurring prompt — supports every 5m, every 1h, daily 9am, weekdays 14:00, mon,wed,fri 10:30, or a raw 5-field cron. Options: --max-runs N, --label "...". Each fire posts a "🔔 Scheduled" header and runs through the current session.
/schedules
List active scheduled tasks for this chat with id, next-fire time, run count, and the prompt preview
/unschedule <id>
Remove a scheduled task by id (get the id from /schedules)
/teleport
Move session to terminal (forked)
Agent Modes
/provider
Switch AI provider (Claude / CCR / OpenCode)
/method
Switch Claude transport: SDK (default) or PTY (drives an interactive Claude Code session over a pseudo-terminal — experimental, intended to stay on the Pro/Max subscription after the 2026-06-15 programmatic-usage split).
/ccr
Toggle routing through Claude Code Router (sticky fallback when Max runs out)
/model
Switch AI model (provider-aware). Works in both SDK and PTY mode; in PTY mode Claude Code restarts on your next message to pick it up, keeping the conversation. Reports the model that actually served the last turn rather than a default.
/effort <level>
Set reasoning effort (low/medium/high/xhigh/max/auto). Works in both SDK and PTY mode; in PTY mode Claude Code restarts on your next message to pick it up, keeping the conversation. Enable /statusline to see the current level's icon (🐇/⚖️/🧠/🔬/🚀) after each turn.
/verbosity <tier>
Pick how much detail TeleCoder surfaces per turn (quiet / normal / verbose / debug). Verbose adds the per-turn usage footer, untruncated tool inputs, and a consolidated action log that streams live then collapses to a Telegraph link at the end of the turn. Debug extends the action log with longer previews (40 lines vs 20); quiet suppresses the completion ping. Per-chat — overrides VERBOSITY_DEFAULT.
/btw <question>
Ask a side question without interrupting the current task. Works in both modes: SDK mode uses the live query's side-question channel, PTY mode answers from a read-only, non-persisted fork of the running session — so the transcript is never touched and the turn keeps going.
/tasks
List active background tasks; tap a number to view details
/shells
List OS-level background shells spawned by the PTY claude session (e.g. Bash(run_in_background=true) pollers, Monitor loops). Each row shows age, PID, and the cmdline so you can decide before tapping — buttons SIGTERM that process and its descendants. Rescues sessions hung on a watcher whose condition will never fire.
/mode
Toggle streaming vs wait response mode
/terminalui
Toggle terminal-style display with spinners
/statusline
Toggle per-turn status line (effort, model, context %, cost) with sub-toggles for topic, your last prompt, and a copy-pasteable claude --resume command
/botname
Toggle dynamic bot name (shows the active project)
/suggestions
Toggle predicted next-prompt buttons. When on, TeleCoder scrapes Claude Code's ghost-text suggestion from the TUI at end-of-turn and surfaces it as a tappable inline button under each response. Takes effect on next session spawn.
/topic <text>
Set or clear the conversation topic (shown in the status line when enabled)
/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. When it has to ask the CLI directly it does so on a throwaway fork, so the live conversation's transcript is never written to.
/compact
Compact the context window (PTY mode) — runs native Claude Code compaction and replies with the token reduction. In SDK mode it explains that manual compaction is PTY-only.
/cancel
Cancel current request (alias: /stop)
/commands
Show all available commands
/ping
Health check (bypasses processing queue)
/botstatus
Show bot process status
/restartbot
Restart the bot — inline menu picks this instance, all instances, or cancel
/rebuildbot
Rebuild code and restart — inline menu picks this instance, all instances, or cancel
/update
Update the Claude Code CLI — confirms with current version, then runs claude update
Community
Contributors
TeleCoder began in February 2026 as a fork of Claudegram by Nacho Mascort, and is maintained independently today. That project is the foundation this one is built on.
