Iris is a Telegram bridge for Claude Code that connects your Telegram app to your Claude Code sessions running inside VS Code. In other words, you can walk away from your computer, open Telegram on your phone, and send messages directly into your active Claude Code conversation. Claude responds, and the response lands back in your Telegram chat.
Additionally, Iris was built to solve a specific problem that every developer using AI coding agents faces: you start a long-running task with Claude Code, step away from your desk, and lose all visibility into what the agent is doing. Moreover, you cannot give it new instructions until you sit back down in front of your computer.
Furthermore, this Telegram bridge for Claude Code works entirely inside VS Code as a native extension. There are no external servers, no third-party services, and no subscription fees. Your messages travel directly between Telegram and your local VS Code instance.
Why You Need a Telegram Bridge for Claude Code
AI coding agents like Claude Code can run for minutes or even hours on complex tasks. They read files, write code, run tests, fix errors, and iterate — all without human input. However, there are moments when the agent needs a decision. It hits a fork in the road and asks you a question. If you are not at your desk, the agent stops and waits.
Specifically, here are the scenarios where a Telegram bridge for Claude Code changes your workflow:
- You are in a meeting — Claude finishes a refactoring task and asks which approach to take for the next step. You answer from Telegram without leaving the meeting.
- You are on the train — Claude encounters a test failure and asks whether to fix it or skip it. You reply from your phone in seconds.
- You are at lunch — Claude completes a deployment and sends you the results. You review the output in Telegram and approve the next task.
- You are working on another project — Claude in VS Code Window 1 needs input. You respond via Telegram without switching windows or breaking your focus on Window 2.
In short, Iris turns Claude Code from a tool you sit in front of into a tool you carry in your pocket.
How the Telegram Bridge for Claude Code Works
Iris operates as a bidirectional message bridge between Telegram and VS Code:
- You send a message in Telegram to your Iris bot.
- Iris receives the message via the Telegram Bot API and routes it to your active Claude Code conversation in VS Code.
- Claude Code processes the message as if you typed it directly in the VS Code chat panel.
- Claude responds, and Iris relays the response back to your Telegram chat.
In addition, the entire round trip happens in seconds. The bridge uses Telegram’s long polling for instant message delivery and VS Code’s extension API for injecting messages into Claude Code conversations.
Most importantly, all messages stay between your phone and your computer. Iris does not route messages through any external server. The Telegram Bot API communicates directly with the extension running on your machine.
Key Features
Iris was built with security and reliability as core requirements:
- Two-way messaging — send messages from Telegram to Claude Code and receive responses back. Full bidirectional communication.
- Window routing — if you have multiple VS Code windows open, use
/prefixsyntax to direct messages to a specific window. Each window can run its own Claude Code session. - TOFU security — Trust-on-First-Use model. The first person to message your bot gets approved automatically. After that, new senders require explicit approval via a VS Code prompt.
- Encrypted storage — your Telegram bot token is stored in VS Code’s SecretStorage, which uses your operating system’s native keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service).
- Local persistence — message history is stored in a local SQLite database using sql.js (WASM). Your messages survive VS Code restarts and extension updates.
- Leader election — when multiple VS Code windows are open, Iris automatically elects a leader to handle incoming messages. If the leader window closes, another window takes over seamlessly.
- Network resilience — exponential backoff with jitter handles network interruptions gracefully. If your connection drops, Iris reconnects automatically when the network returns.
Notably, the extension adds zero overhead to VS Code when idle. It polls Telegram only when active and processes messages asynchronously.
Setting Up Iris
Getting started takes three steps:
Step 1: Install the Extension
Install Iris from the VS Code Marketplace or search for “Iris for Claude” in the VS Code extensions panel.
Step 2: Create a Telegram Bot
Next, open Telegram and message @BotFather to create a new bot. BotFather gives you a bot token — a long string that looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Copy this token.
After that, open VS Code’s command palette and run Iris: Configure. Paste your bot token when prompted. The extension validates the token and starts listening for messages.
Step 3: Send Your First Message
Finally, open Telegram and send a message to your new bot. Iris displays a TOFU approval prompt in VS Code. Click Approve, and the bridge is live. From that point forward, every message you send in Telegram lands in your Claude Code conversation, and every response from Claude comes back to Telegram.
Platform Support
| Platform | Message Injection | Transcript Relay |
|---|---|---|
| macOS | Full support | Full support |
| Linux | Coming soon | Full support |
| Windows | Coming soon | Full support |
Specifically, message injection (sending Telegram messages into Claude Code conversations) requires platform-specific integration with the VS Code terminal. macOS has full support today. Linux and Windows support transcript relay (seeing Claude’s output in Telegram) with message injection coming in a future update.
Iris vs Other Telegram-Claude Bridges
Several open-source projects connect Telegram to Claude Code. However, Iris takes a fundamentally different approach:
| Feature | Iris | Other Bridges |
|---|---|---|
| Architecture | VS Code extension (native) | Standalone bots (tmux/SDK) |
| Installation | One-click from Marketplace | Git clone + manual setup |
| Session management | Connects to existing VS Code sessions | Creates new Claude sessions |
| Multi-window | Leader election + window routing | Single session only |
| Credential storage | OS keychain via SecretStorage | Environment variables or config files |
| Dependencies | Zero (sql.js WASM only) | Python/Node + multiple packages |
In fact, most other bridges create a new Claude Code session in tmux. As a result, they cannot connect to the Claude Code conversation you already have running in VS Code. Iris solves this by operating as a native VS Code extension that integrates directly with your existing sessions.
Security Model
Iris uses a Trust-on-First-Use (TOFU) security model. Specifically, here is how authentication works:
- You create a private Telegram bot via BotFather. Only people who know your bot’s username can message it.
- The first person to message the bot gets approved automatically and becomes the trusted sender.
- If anyone else messages the bot, VS Code shows a prompt asking whether to approve or reject the sender.
- Approved senders are stored locally. Rejected senders cannot communicate with your Claude Code sessions.
Moreover, your bot token is never written to disk as plain text. It is stored exclusively in VS Code’s encrypted SecretStorage. Similarly, the SQLite message database stays on your local machine and is never transmitted anywhere.
Common Questions
Do I need a Telegram Premium account?
No. Iris works with any free Telegram account. In fact, the bot API used by Iris is part of Telegram’s free tier and has no usage limits for personal bots.
Can other people message my Claude Code?
Only if you approve them. The TOFU security model requires explicit approval for every sender after the first. Additionally, since your bot is private, only people who know its username can find it.
What happens if VS Code closes while I am away?
Messages sent to your Telegram bot are queued by Telegram’s servers. Consequently, when you reopen VS Code and Iris reconnects, any queued messages are delivered. No messages are lost.
Can I use Iris with agents other than Claude Code?
Iris was designed specifically as a Telegram bridge for Claude Code. However, the message injection mechanism works with any terminal-based AI agent running in VS Code. Specifically, if your agent accepts text input via the VS Code terminal, Iris can route Telegram messages to it.
Part of a Collection of VS Code Extensions
Iris is part of a collection of VS Code extensions built for AI-assisted development:
- Arc Terminal Bridge — gives AI agents full terminal control inside VS Code with complete output capture.
- GA4 Analytics MCP — query Google Analytics 4 data directly from your AI agent.
Similarly, these extensions were built by the same developer behind the Contact Form 7 Mailchimp Extension and the other free WordPress plugins that have been downloaded nearly 10 million times since 2015.
Getting Started
Iris is a Telegram bridge for Claude Code that turns your AI coding agent into a tool you can access from anywhere. As a result, you stay connected to your Claude Code sessions whether you are at your desk, in a meeting, or on the train.
Additionally, if you need help with setup or have questions, contact us directly. For more tools built for developers, visit Arc Terminal Bridge and GA4 Analytics MCP.