Agent Reachout

Let your Claude Code message you on Telegram when it needs decisions or finishes work, even when you’re away from your desk.

Claude Code → Agent Reachout → Telegram → Human reply → Agent continues

---

Why?

AI agents are great at doing work, but real workflows still need human judgment.

In practice, agents:

• hit ambiguous decisions
• need approval before destructive actions
• finish long tasks while you’re not watching the terminal

Dashboards assume you go check them.
Messaging flips the model — the agent comes to you only when needed.

Agent Reachout turns agent workflows into something asynchronous and interrupt-driven, without babysitting the CLI.

---

What it does

• Sends notifications to Telegram when an agent:
  • finishes a task
  • hits a blocker
  • needs a decision
• Supports one-way notifications or two-way conversations
• Lets the agent pause → ask → resume
• Designed for human-in-the-loop agent workflows

Currently implemented as a Claude Code plugin.

---

Why Telegram first?

This started as a personal workflow tool, not a team platform.

Telegram was chosen because:

• it’s already on my phone
• fast setup and low friction
• feels like a push notification, not another dashboard
• works well for solo devs and small setups

The concept is channel-agnostic — Telegram is just the first integration.

---

What it’s not

• Not a workflow engine
• Not a chatbot framework
• Not a full agent orchestration system

It’s a small bridge between agents and humans.

---

Use cases

• Approving file changes or deletions
• Answering clarification questions mid-task
• Getting notified when long-running tasks complete
• Running agents asynchronously without monitoring logs

---

Installation

Prerequisites

• Claude Code CLI installed
• Bun installed (https://bun.com/docs/installation)
• A Telegram account

---

1. Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts to create your bot
3. Copy the bot token (looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

---

2. Get Your Telegram Chat ID

1. Search for @userinfobot on Telegram
2. Start a chat with it
3. Copy your chat ID (a number like 123456789)

Tip: Start a conversation with your newly created bot first by searching for it and clicking "Start".

---

3. Configure Environment Variables

Set the following environment variables. You can add them to your shell profile (.zshrc, .bashrc) or set them before running Claude Code:

Shell format:

export AGENT_REACHOUT_TELEGRAM_BOT_TOKEN=your_bot_token_here
export AGENT_REACHOUT_TELEGRAM_CHAT_ID=your_chat_id_here

Or in your Claude Code settings (~/.claude/settings.json):

{
  "env": {
    "AGENT_REACHOUT_TELEGRAM_BOT_TOKEN": "your_bot_token_here",
    "AGENT_REACHOUT_TELEGRAM_CHAT_ID": "your_chat_id_here"
  }
}

Environment Variables Reference