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 default
Dangerous mode — opt-in auto-approve for all tool permissions
Secrets — loaded from .env (gitignored), never committed

Credits

Original project by NachoSEO. Extended with Reddit video downloads, voice transcription, TTS, Medium integration, Telegraph output, image uploads, and session continuity.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 142 Commits
docs		docs
scripts		scripts
src		src
.coderabbit.yaml		.coderabbit.yaml
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Claudegram

What is this?

Features

Agent Core

Reddit Integration

Media Extraction

Medium Integration

Voice & Audio

Rich Output

Terminal UI

MCP Tools (Intelligent Routing)

Forum Topic Sessions

Image Uploads

Quick Start

Prerequisites

Setup

Run

Commands

Session

Agent Modes

Content

Voice & TTS

Utility

Optional Integrations

Configuration Reference

Required

Core

Reddit

Medium / Freedium

Media Extraction

Voice & TTS

Architecture

Development

Bot Control Script

Self-Editing Workflow

Security

Credits

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages