Claudegram

Your personal AI agent, running on your machine, controlled from Telegram.

  Telegram  ──▶  Grammy Bot  ──▶  Claude Agent SDK  ──▶  Your Machine
  voice/text     command router     agentic runtime       bash, files, code

---

What is this?

Claudegram bridges Telegram to a full Claude Code agent running locally on your machine. Send a message in Telegram — Claude reads your files, runs commands, writes code, browses Reddit, fetches Medium articles, transcribes voice notes, and speaks responses back. All from your phone.

This is not a simple API wrapper. It's the real Claude Code agent with tool access — Bash, file I/O, code editing, web browsing — packaged behind a Telegram interface with streaming responses, session memory, and rich output formatting.

---

Features

### Agent Core - Full Claude Code with tool access (Bash, Read, Write, Edit, Glob, Grep) - Session resume across messages — Claude remembers everything - Project-based working directories - Streaming responses with live-updating messages - Model picker: Sonnet · Opus · Haiku - Plan mode, explore mode, loop mode ### Reddit Integration - `/reddit` — posts, subreddits, user profiles - `/vreddit` — download & send Reddit-hosted videos - Auto-compression for videos > 50 MB (CRF → two-pass) - Original oversized videos archived locally - Large threads auto-export to JSON ### Media Extraction - `/extract` — YouTube, Instagram, TikTok video/audio/transcript - Text, audio (MP3), video (MP4), or all modes - Requires yt-dlp, ffmpeg (system binaries) ### Medium Integration - `/medium` — fetch paywalled articles via Freedium - Telegraph Instant View, save as Markdown, or both - Pure TypeScript, no Python/Playwright needed

### Voice & Audio - Send a voice note → transcribed via Groq Whisper → fed to Claude - `/transcribe` — standalone transcription (reply-to or prompt) - `/tts` — agent responses spoken back as Telegram voice notes - 13 voices via OpenAI TTS (`gpt-4o-mini-tts`) ### Rich Output - MarkdownV2 formatting with automatic escaping - Telegraph Instant View for long responses & tables - Smart chunking that preserves code blocks - ForceReply interactive prompts for multi-step commands - `/teleport` — fork session to terminal for continued work - Inline keyboards for settings (model, mode, TTS, clear) ### Terminal UI - Terminal-style display with tool status spinners - Shows what Claude is doing in real time - Toggle with `/terminalui` ### MCP Tools (Intelligent Routing) - Talk naturally — Claude auto-uses the right tools - Reddit, Medium, YouTube, project management via MCP - No explicit commands needed for common tasks ### Forum Topic Sessions - Each forum topic runs as an independent session - Work on multiple projects in parallel across topics ### Image Uploads - Send photos or image docs in chat - Saved to project under `.claudegram/uploads/` - Claude is notified with path + caption

---

Quick Start

Prerequisites

Requirement	Notes
Node.js 18+	with npm
Claude Code CLI	installed and authenticated — claude in your PATH
Telegram bot token	from @BotFather
Your Telegram user ID	from @userinfobot

Setup

git clone https://github.com/NachoSEO/claudegram.git
cd claudegram
cp .env.example .env

Edit .env:

TELEGRAM_BOT_TOKEN=your_bot_token
ALLOWED_USER_IDS=your_user_id

Run

npm install
npm run dev        # dev mode with hot reload

Open your bot in Telegram → /start

---

Commands

Session

Command	Description
/start	Welcome message
/project	Set working directory (interactive picker)
/newproject <name>	Create and switch to a new project
/clear	Clear conversation + session
/status	Current session info
/sessions	List saved sessions
/resume	Pick from recent sessions
/continue	Resume most recent session
/teleport	Move session to terminal (forked)

Agent Modes

Command	Description
/plan	Plan mode for complex tasks
/explore	Explore codebase to answer questions
/loop	Run iteratively until task complete
/model	Switch Sonnet / Opus / Haiku
/mode	Toggle streaming / wait
/terminalui	Toggle terminal-style display

Content

Command	Description
/reddit	Fetch Reddit posts, subreddits, profiles
/vreddit	Download Reddit-hosted videos
/medium	Fetch Medium articles via Freedium
/file	Download a project file
/telegraph	Toggle Instant View for long responses
/extract <url>	Download media from YouTube, TikTok, Instagram

Voice & TTS

Command	Description
/tts	Toggle voice replies, pick voice
/transcribe	Transcribe audio to text
Send voice note	Auto-transcribed → processed by Claude

Utility

Command	Description
/ping	Health check
/context	Show Claude context / token usage
/botstatus	Bot process status
/restartbot	Restart the bot
/cancel	Cancel current request
/commands	Show all commands
/softreset	Soft reset (cancel + clear session)

---

Optional Integrations

Reddit — /reddit & /vreddit

/reddit is now a pure TypeScript module using Reddit's OAuth2 API directly — no external Python dependency.

# .env
REDDIT_CLIENT_ID=your_client_id
REDDIT_CLIENT_SECRET=your_client_secret
REDDIT_USERNAME=bot_account
REDDIT_PASSWORD=bot_password

Create a "script" app at https://www.reddit.com/prefs/apps/. Use a dedicated bot account — NOT your personal credentials. Video downloads need ffmpeg and ffprobe on your PATH.

Medium — /medium

Pure TypeScript via Freedium mirror — no extra dependencies.

# .env (optional tuning)
FREEDIUM_HOST=freedium-mirror.cfd
MEDIUM_TIMEOUT_MS=15000

Voice Transcription — Groq Whisper

# .env
GROQ_API_KEY=your_groq_key
GROQ_TRANSCRIBE_PATH=/absolute/path/to/groq_transcribe.py

Text-to-Speech — OpenAI TTS

# .env
OPENAI_API_KEY=your_openai_key
TTS_MODEL=gpt-4o-mini-tts
TTS_VOICE=coral
TTS_RESPONSE_FORMAT=opus

13 voices available: alloy, ash, ballad, cedar, coral, echo, fable, marin, nova, onyx, sage, shimmer, verse

---

Configuration Reference

All config lives in .env. See .env.example for the full annotated reference.

Required

Variable	Description
TELEGRAM_BOT_TOKEN	Bot token from @BotFather
ALLOWED_USER_IDS	Comma-separated Telegram user IDs

Core

Variable	Default	Description
ANTHROPIC_API_KEY	—	API key (optional with Claude Max subscription)
WORKSPACE_DIR	$HOME	Root directory for project picker
CLAUDE_EXECUTABLE_PATH	claude	Path to Claude Code CLI
BOT_NAME	Claudegram	Bot name in system prompt
STREAMING_MODE	streaming	streaming or wait
DANGEROUS_MODE	false	Auto-approve all tool permissions
CANCEL_ON_NEW_MESSAGE	false	Auto-cancel running query on new message
CLAUDE_SDK_LOG_LEVEL	off	SDK log level: off, basic, verbose, trace

Reddit

Variable	Default	Description
REDDIT_CLIENT_ID	—	Reddit OAuth2 client ID
REDDIT_CLIENT_SECRET	—	Reddit OAuth2 client secret
REDDIT_USERNAME	—	Reddit bot account username
REDDIT_PASSWORD	—	Reddit bot account password
REDDIT_VIDEO_MAX_SIZE_MB	50	Max video size before compression
REDDITFETCH_TIMEOUT_MS	30000	Execution timeout
REDDITFETCH_JSON_THRESHOLD_CHARS	8000	Auto-switch to JSON output

Medium / Freedium

Variable	Default	Description
FREEDIUM_HOST	freedium-mirror.cfd	Freedium mirror host
MEDIUM_TIMEOUT_MS	15000	Fetch timeout
MEDIUM_FILE_THRESHOLD_CHARS	8000	File save threshold

Media Extraction

Variable	Default	Description
EXTRACT_ENABLED	true	Enable /extract command
YTDLP_COOKIES_PATH	—	Netscape cookies.txt for yt-dlp

Voice & TTS

Variable	Default	Description
GROQ_API_KEY	—	Groq API key for Whisper
GROQ_TRANSCRIBE_PATH	—	Path to groq_transcribe.py
OPENAI_API_KEY	—	OpenAI API key for TTS
TTS_VOICE	coral	Default TTS voice
TTS_MODEL	gpt-4o-mini-tts	TTS model
VOICE_SHOW_TRANSCRIPT	true	Show transcript text before agent response

---

Architecture

src/
├── bot/
│   ├── bot.ts                     # Bot setup, handler registration
│   ├── handlers/
│   │   ├── command.handler.ts     # All slash commands + inline keyboards
│   │   ├── message.handler.ts     # Text routing, ForceReply dispatch
│   │   ├── voice.handler.ts       # Voice download, transcription, agent relay
│   │   └── photo.handler.ts       # Image save + agent notification
│   └── middleware/
│       ├── auth.middleware.ts      # User whitelist + group chat auth
│       └── stale-filter.ts        # Ignore stale messages on restart
├── claude/
│   ├── agent.ts                   # Claude Agent SDK, session resume, system prompt
│   ├── mcp-tools.ts              # MCP server: Reddit, Medium, Extract, Telegraph tools
│   ├── session-manager.ts         # Per-chat session state
│   ├── session-history.ts         # Session persistence and history
│   ├── request-queue.ts           # Sequential request queue
│   ├── command-parser.ts          # Help text + command descriptions
│   └── agent-watchdog.ts          # Watchdog for long-running agent tasks
├── reddit/
│   ├── redditfetch.ts             # Native TypeScript Reddit client (OAuth2)
│   └── vreddit.ts                 # Reddit video download + compression pipeline
├── medium/
│   └── freedium.ts                # Freedium article fetcher
├── media/
│   └── extract.ts                 # YouTube/TikTok/Instagram extraction (yt-dlp)
├── telegram/
│   ├── message-sender.ts          # Streaming, chunking, Telegraph routing
│   ├── markdown.ts                # MarkdownV2 escaping
│   ├── telegraph.ts               # Telegraph Instant View client
│   ├── telegraph-settings.ts      # Per-chat Telegraph toggle
│   ├── terminal-renderer.ts       # Terminal-style UI renderer
│   ├── terminal-settings.ts       # Per-chat terminal UI toggle
│   └── deduplication.ts           # Message dedup
├── tts/
│   ├── tts.ts                     # TTS provider routing (Groq Orpheus / OpenAI)
│   ├── tts-settings.ts            # Per-chat voice settings
│   └── voice-reply.ts             # TTS hook for agent responses
├── audio/
│   └── transcribe.ts              # Shared transcription utilities
├── utils/
│   ├── download.ts                # URL download with SSRF protection
│   ├── sanitize.ts                # Path and error sanitization
│   ├── workspace-guard.ts         # Workspace boundary enforcement
│   ├── url-guard.ts               # URL validation (protocol, SSRF)
│   ├── file-type.ts               # File content validation
│   ├── caffeinate.ts              # macOS sleep prevention
│   ├── session-key.ts             # Session key generation (DM + forum topics)
│   ├── agent-timer.ts             # Agent execution timing
│   └── debug-agent.ts             # Debug utilities
├── config.ts                      # Zod-validated environment config
└── index.ts                       # Entry point

---

Development

npm run dev          # Dev mode with hot reload (tsx watch)
npm run typecheck    # Type check only
npm run build        # Compile to dist/
npm start            # Run compiled build

Bot Control Script

./scripts/claudegram-botctl.sh dev start      # Start dev mode
./scripts/claudegram-botctl.sh dev restart     # Restart dev
./scripts/claudegram-botctl.sh prod start      # Start production
./scripts/claudegram-botctl.sh dev log         # Tail logs
./scripts/claudegram-botctl.sh dev status      # Check if running

Self-Editing Workflow

If Claudegram is editing its own codebase, use prod mode to avoid hot-reload restarts:

./scripts/claudegram-botctl.sh prod start      # No hot reload
# ... let Claude edit files ...
./scripts/claudegram-botctl.sh prod restart     # Apply changes

Then /continue or /resume in Telegram to restore your session.

---

Security

• User whitelist — only approved Telegram IDs can interact
• Project sandbox — Claude operates within the configured working directory
• Permission mode — uses acceptEdits by defau