polygram

polygram

A Telegram daemon and Claude Code plugin that preserves the per-chat session model from OpenClaw. Intended primarily as a migration path for users moving their Telegram-based ops from OpenClaw to Claude Code, after OpenClaw dropped Claude support.

If you ran OpenClaw with multiple Telegram chats — each with its own context, its own memory, its own transcript — polygram gives you that shape back on top of claude CLI. Install as a daemon, a Claude plugin, or both.

Background

OpenClaw ran a Telegram agent with one conversation context per chat. Each chat had its own persistent memory; topics in a forum chat could optionally carry their own sub-context. The agent, cron scripts, and human operators all wrote into a shared transcript.

OpenClaw no longer supports Claude. Migrating to Claude Code loses that model unless it's rebuilt. The official telegram@claude-plugins-official plugin is single-session — one Claude Code process, one bot, one shared context across all chats. Third-party Claude Code Telegram bots usually share one session across all users of a given bot instance.

polygram is the shape that keeps OpenClaw's per-chat-session ergonomics while running on top of claude CLI.

What it is

• One Node process per bot. Required --bot <name> flag. N bots = N processes. No "one process hosts many bots" mode — crash isolation is the point.
• Per-chat Claude sessions. Each chat has its own claude_session_id, resumed via claude --resume.
• Per-topic sessions — opt-in (isolateTopics: true in chat config). Default is shared context across topics, since topics are usually organisational. OpenClaw migrators who used per-topic separation can keep it with one flag.
• SQLite transcripts (WAL, FTS5, numbered migrations, user_version).
• Write-before-send atomicity. Outbound messages hit the DB as pending before the Telegram call, flip to sent or failed after. Boot sweep resolves stale pending rows from the last crash.
• Unix-socket IPC per bot. Cron jobs and Claude Code approval hooks talk to the bot process over /tmp/polygram-<bot>.sock. The bot is the only writer to its own DB.
• Inline-keyboard approvals. Destructive tool calls gate on operator click via Claude Code's PreToolUse hook; 5-minute auto-deny.
• Voice transcription. OpenAI Whisper API or local whisper.cpp, selectable per bot. Transcriptions land in messages.text so FTS finds them.
• Per-attachment table (attachments, since 0.6.0) with download lifecycle (pending → downloaded | failed), per-attachment transcription, and chat_id/kind/status indexes for ops queries. Replaces the older attachments_json blob — query "all PDFs Maria sent last week" without scanning every message. Failed downloads surface to Claude as <attachment-failed reason="..." /> so the user gets a real explanation, not silence.
• Content-addressed attachment storage via Telegram's file_unique_id. Same photo forwarded twice = one file on disk. Multi-photo albums (Telegram delivers each photo as a separate message sharing media_group_id) coalesce into one logical turn so Claude sees the whole album, not just the first photo.
• Prompt-injection hardening. User text wrapped in <untrusted-input> with xml-escape; attributes use ". A partner typing </channel><system>... sees it as literal text in the prompt.
• Pairing codes for guest onboarding without polygram restart (/pair-code, /pair <CODE>, /pairings, /unpair).
• Step-level streaming replies (optional per bot). Telegram message edits on each assistant step as Claude works through tool calls and reasoning.
• Crash-resilient handler lifecycle. Inbound rows track a handler_status (received → dispatched → replied | failed | replay-pending). On graceful shutdown, in-flight turns are marked for replay; on next boot the daemon re-dispatches anything within a 3-minute window, deduped against already-sent outbound replies. One-shot guard prevents replay loops.
• Contextual error replies. Idle timeouts, wall-clock ceilings, and process crashes each get a distinct user-facing message with a recovery hint, not a generic "something went wrong." Restarts and user-issued aborts don't fire the apology at all.
• Abort detection in natural language (stop, cancel, wait, стоп, отмена, хватит, ...) plus the slash forms (/stop, /abort, /cancel). First-sentence match catches "Stop. I'll ask