TeleClaude for Claude Code in Telegram

TeleClaude: Self-Hosted Telegram Bot for Isolated Claude Code Sessions

After the OpenClaw shutdown, developers lost access to Claude Code via Telegram. TeleClaude fixes that: a TypeScript app on Bun that spins up local Claude Code CLI processes, routing messages from supergroup topics to isolated project directories. It uses OAuth auth from your own Claude subscription—no middlemen.

Architecture and Routing

TeleClaude hooks into the Telegram Bot API via Grammy. Every message from a supergroup topic spawns a dedicated Claude Code process with its own project folder. It supports session continuity, context compression, and memory deduplication.

Telegram Bot API → Grammy Router → Process Manager → Claude Code CLI (per topic)

Key components:

• Topic-based routing with context injection.
• Process manager with TTL, concurrency limits, and cleanup.
• File-based memory: SOUL.md (personality), main-memory.md (shared knowledge base), topic-memory.md (project history).

Memory System and Levels

Memory is structured in three tiers to preserve context across sessions:

project/
├── SOUL.md              # Communication style, rules
├── main-memory.md       # Symlink to shared knowledge base
├── topic-memory.md      # Auto-updating project history
└── memory/
    ├── people/
    ├── services/
    ├── shared/
    └── projects/

Claude Code updates topic-memory.md on its own. On restart or session reset, context reloads from files. Deduplication periodically strips duplicates across files.

Project Automation and Compression

A new topic in the supergroup auto-creates a directory from templates/. The bot links SOUL.md, main-memory.md, and initializes memory. The first message kicks off Claude Code with full context ready.

Compression kicks in near context limits: key facts save to memory, session resets. Use /compact to trigger manually.

TeleClaude Features

• Topic Routing: Isolated processes and directories.
• Persistent Memory: Three tiers with cross-project access.
• Auto-Project Creation: Templates for new topics.
• Voice Messages: Optional local Whisper transcription.
• Streaming: Typing indicator and incremental updates.
• Models: Opus, Sonnet, Haiku, or local via Claude Code.
• Management: TTL, limits, process kills.

Installation and Setup

Requirements: Bun 1.0+, authorized Claude Code CLI, Telegram bot, supergroup with topics.

git clone https://github.com/devladpopov/teleclaude.git
cd teleclaude
bun install
cp .env.example .env
cp config/settings.example.json config/settings.json
bun run start

In settings.json, set allowedUsers, ttlMinutes (default 30), maxConcurrent (5), claudePath.

Bot Commands

| Command | Description |

|---------|-------------|

| /help | Command list |

| /status | Active processes, status |

| /ttl N | Idle timeout (1–1440 min) |

| /name <name> | Rename topic |

| /reset | Reset with memory preserved |

| /kill | Stop topic process |

| /memory | Memory stats |

TeleClaude vs OpenClaw

| Aspect | TeleClaude | OpenClaw |

|--------|------------|----------|

| Hosting | Self-hosted | Cloud |

| Backend | Claude Code CLI | API |

| Auth | Your OAuth subscription | Managed |

| Cost | Just Claude sub | Extra fees |

| Memory | File-based, persistent | Built-in |

Key Highlights

• Full topic isolation without window switching.
• Self-hosted, no costs beyond Claude subscription.
• Auto-compression and context recovery.
• Voice support via Whisper and streaming replies.
• MIT license, customizable templates and settings.

— Editorial Team