Why Not a Web Dashboard?
When you build a monitoring tool, the default instinct is to build a web dashboard. A React app with charts, tables, and a real-time WebSocket feed. Every monitoring product in existence does this.
We considered it for CodePulse and rejected it. Here is why.
Dashboards require infrastructure
A web dashboard needs a server. That server needs authentication, HTTPS certificates, session management, and a database to store state. It needs to be accessible from outside your local network, which means either a cloud deployment or a tunneling solution. Every one of these components adds complexity, cost, and attack surface.
CodePulse is a local-first tool. Adding a server-hosted dashboard would contradict the core architecture. Your data stays on your machine, so the monitoring interface must reach you without requiring your data to leave your machine.
Dashboards do not push
You do not sit in front of a dashboard waiting for events. You check it when you remember to, which is usually after something has already gone wrong. What you actually need is a push notification that reaches you wherever you are and lets you respond immediately.
Web push notifications exist, but they are unreliable across browsers, require service workers, and cannot carry interactive buttons. They are a notification, not a conversation.
Dashboards are the wrong interaction model
When Claude Code asks "Can I run rm -rf dist && npm run build?", you need to answer yes or no. That is a message, not a dashboard metric. The interaction model is conversational: the agent tells you something, you respond, the agent continues. A chat interface is the natural fit.
Why Telegram Specifically?
We evaluated several messaging platforms: Slack, Discord, WhatsApp, Signal, and Telegram. Telegram won on every criterion that mattered.
Free, unrestricted bot API
Telegram's Bot API is free with no rate limits that matter for our use case. You create a bot in 30 seconds via BotFather, get a token, and start sending messages. No OAuth flows, no app review process, no monthly fees. Slack's API has rate limits and requires workspace installation. Discord requires server creation. WhatsApp Business API requires Facebook Business verification.
Rich message formatting
Telegram bots can send messages with Markdown formatting, inline buttons, callback queries, images, and file attachments. This lets CodePulse create rich interactive cards for permission requests, commit reviews, and status updates. A permission request is not just a text message; it is a card with the command, context, and Allow/Deny/Instruct buttons.
Cross-platform with reliable notifications
Telegram works on iOS, Android, macOS, Windows, Linux, and the web. Notifications arrive reliably and consistently. You can respond from your phone's lock screen with a single tap on an inline button. This matters when Claude is waiting for a permission response and every second counts.
Voice message support
Telegram natively supports voice messages. CodePulse leverages this for voice input: record a voice message, and it gets transcribed and forwarded to Claude Code as a text instruction. No additional app needed.
Topic-based groups
Telegram groups support topics (threads within a group). CodePulse uses this for multi-project routing: each project gets its own topic in a Telegram group, so messages from different Claude Code sessions do not overlap.
The Bidirectional Architecture
CodePulse is not a one-way notification tool. It is bidirectional. You can send instructions back to Claude Code through Telegram, and they get injected into the active session's conversation context.
This works because of Claude Code's --input-format stream-json protocol.
How stream-json works
Claude Code supports a bidirectional JSON protocol for programmatic control. When you start Claude Code with the --input-format stream-json --output-format stream-json flags, it reads structured JSON messages from stdin and writes NDJSON (newline-delimited JSON) events to stdout.
CodePulse spawns a Claude Code process with these flags. It reads the output stream to track what the agent is doing, and it writes to the input stream when you send a message from Telegram.
[Telegram] --> [CodePulse] --> stdin --> [Claude Code]
|
[Telegram] <-- [CodePulse] <-- stdout <-------+
Each message you send from Telegram becomes an SDKUserMessage JSON object written to Claude Code's stdin. Each response from Claude Code is a JSON event on stdout that CodePulse parses and routes to the appropriate Telegram message or notification.
Resume-per-message architecture
Claude Code supports session resumption via the --resume sessionId flag. This lets you continue a previous conversation with full context. CodePulse uses this mechanism to maintain continuity across messages.
When you send a message from Telegram, CodePulse either writes to the active session's stdin (if the process is still running) or spawns a new Claude Code process with --resume pointing to the session ID. This ensures your instruction is processed with the full conversation history as context.
This resume-per-message approach also works around platform-specific reliability issues. If a Claude Code process crashes or exits unexpectedly, the next message simply resumes the session in a new process.
The Smart Classifier
Not every Telegram message should be forwarded to Claude Code. CodePulse includes a classifier that determines the intent of your message:
- Approval responses ("yes", "allow", "deny", tapping an inline button) are routed to the approval pipeline
- Direct instructions ("refactor the auth module", "add error handling to the API") are forwarded to Claude Code as user prompts
- Queries about the session ("what are you doing?", "status") trigger a status report from CodePulse itself, without interrupting Claude
- Voice messages are transcribed first, then classified the same way
This classification prevents accidental interruptions. If you are chatting with someone else in the Telegram group, CodePulse does not forward those messages to Claude.
What Flows Through Telegram
Here is what appears in your Telegram conversation during a typical Claude Code session.
Permission request cards
When Claude wants to run a command or modify a file, CodePulse sends a formatted card with the tool name, the arguments, and the context. Inline buttons let you Allow, Deny, or add instructions.
Commit review cards
When Claude makes a git commit, CodePulse intercepts it and sends the commit message, a Haiku-generated diff analysis, and the actual diff summary to Telegram. You can Approve, Reject, or Edit the commit message before it lands.
The Pulse updates
Real-time updates about what Claude is doing: reading files, running commands, writing code. These are formatted as concise one-line messages so they do not flood your chat.
Morning Briefing
A daily summary message that arrives in the morning with overnight activity: sessions run, files modified, commits made, tokens consumed, and anything that needs attention.
Your messages back
When you type a message or send a voice note, CodePulse acknowledges it, shows that it is being forwarded to Claude, and then delivers Claude's response back to Telegram.
Latency Considerations
The path from Claude Code event to your Telegram notification involves several steps:
- Claude Code fires a hook event
- CodePulse's hook handler processes the event (sub-millisecond)
- CodePulse sends a Telegram Bot API request (50-150ms depending on network)
- Telegram delivers the notification to your device (varies)
Total latency from event to notification is typically under 500ms. For the reverse path (your Telegram response back to Claude Code), the latency is similar. CodePulse receives the callback via long polling, processes it, and writes to Claude Code's stdin or returns the hook decision. Claude Code receives your response within a second of you tapping the button.
For permission requests, this means Claude waits about 1-2 seconds from when you tap Allow to when it resumes work. In practice, the bottleneck is never the system latency but rather how quickly you notice the notification and respond.
Running Multiple Projects
CodePulse supports monitoring multiple Claude Code sessions simultaneously. Each project is routed to a separate Telegram topic within a group, so session-a's commit reviews do not interleave with session-b's permission requests.
The Telegram group acts as a unified control center: one group for all your projects, one topic per project, full context and history preserved in each topic.
Try It Yourself
CodePulse's Telegram integration is included in the free tier. Setup takes about two minutes: create a Telegram bot via BotFather, add the token to CodePulse's configuration, and run the install command. Your next Claude Code session will start sending notifications to Telegram automatically.
Get started with CodePulse and take your AI coding agent with you.