agent-reachout

Agent Reachout

A minimal Claude Code plugin that lets Claude message you on Telegram.

Start a task, walk away from your computer, and get notified on your phone when Claude finishes work, hits a blocker, or needs a decision. Reply directly from Telegram to keep things moving.

Features

• Mobile-first: Get notifications and respond from your phone, smartwatch, or any Telegram client
• Multi-turn conversations: Have natural back-and-forth dialogue with Claude via Telegram
• Smart hooks: Automatically redirects CLI questions to Telegram and notifies you on task completion
• On-demand activation: Only activates when you say "notify me on telegram" - stays silent otherwise
• Topic support: Send messages to a specific topic in a Telegram group instead of direct messages
• Simple setup: Just a Telegram bot - no paid services or complex infrastructure required

Setup

1. Create a Telegram Bot

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

2. Get Your Chat ID

1. Message @userinfobot on Telegram
2. It will reply with your user ID (a number like 123456789)
3. Start a conversation with your new bot (search for it and send any message)

3. Set Environment Variables

Add these to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export TELEGRAM_BOT_TOKEN="your_bot_token_here"
export TELEGRAM_CHAT_ID="your_chat_id_here"
export TELEGRAM_TOPIC_ID="your_topic_id_here"  # Optional: for group topics

Then reload your shell or run source ~/.zshrc.

4. (Optional) Set Up Group Topics

If you prefer messages in a group topic instead of direct messages:

1. Create a Telegram group and enable Topics (Group Settings > Topics)
2. Add your bot to the group as an admin
3. Create a topic for Claude notifications (e.g., "Claude Updates")
4. Get the topic ID by right-clicking the topic and copying the link - the topic ID is the number after the last slash (e.g., https://t.me/c/1234567890/42 → topic ID is 42)
5. Set TELEGRAM_CHAT_ID to the group ID (negative number, e.g., -1001234567890)
6. Set TELEGRAM_TOPIC_ID to the topic ID

The bot will only send to and receive messages from that specific topic.

Installation

Install via Claude Code:

/plugin marketplace add sidhusmart/agent-reachout
/plugin install agent-reachout@agent-reachout

Restart Claude Code to activate.

Tools

Tool	Description
send_message	Send a message and optionally wait for a response
continue_conversation	Send follow-up in an existing conversation
notify_user	Send one-way notification (no response expected)
end_conversation	Send final message and close conversation

send_message

Starts a new conversation. By default, waits for your reply.

message (required)     Message to send
wait_for_response      Wait for reply (default: true)
timeout_ms             How long to wait in ms (default: 300000 = 5 min)
provider               'telegram' or 'whatsapp' (default: 'telegram')

continue_conversation

Continues an existing conversation. Always waits for response.

conversation_id (required)   ID from previous send_message
message (required)           Message to send
timeout_ms                   How long to wait in ms (default: 300000)

notify_user

Fire-and-forget notification. Does not wait for response.

message (required)     Message to send
conversation_id        Optional: use existing conversation
provider               'telegram' or 'whatsapp' (default: 'telegram')

end_conversation

Sends a final message and marks conversation as ended.

conversation_id (required)   ID of conversation to end
message (required)           Final message to send

Hooks

The plugin includes two hooks that enhance Claude's behavior:

Hook	What it does
Stop	When Claude stops, evaluates if you should be notified about completed work or blockers
PreToolCall: AskUserQuestion	Redirects questions to Telegram instead of the CLI, so you can respond from your phone

On-Demand Activation

Hooks only activate when you explicitly request Telegram notifications at the start of your session. Use phrases like:

• "notify me on telegram"
• "telegram mode"
• "I'm stepping away"
• "notify me"

Examples:

You: "I'm stepping away - please refactor the auth module and notify me on telegram when done"
→ Claude will send updates to Telegram

You: "Refactor the auth module"
→ Claude works normally, no Telegram notifications

This lets you use the plugin for both interactive coding sessions (no notifications) and background tasks (with notifications).

Example Usage