8000 GitHub - drminh2807/agent-cli-telegram: Telegram notifications when Grok/Claude Code agent CLI turns finish (Stop hook) · GitHub
[go: up one dir, main page]

Skip to content

About

Telegram notifications when Grok/Claude Code agent CLI turns finish (Stop hook)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

agent-cli-telegram

Nhận tin nhắn Telegram khi agent CLI (Grok Build / Claude Code) kết thúc lượt làm việc (Stop hook).

Không cần server, không polling — chỉ một shell script gọi Telegram Bot API.

Agent xong lượt  →  Stop hook  →  telegram-notify.sh  →  Telegram

Tính năng

Event Khi nào Tin nhắn
Stop Agent hoàn thành lượt ✅ xong việc + project + full response
StopFailure Lỗi API (Grok) ⚠️ lỗi + full text

Không gửi tin Notification (🔔 cần bạn) — chỉ báo khi agent xong lượt hoặc lỗi.

  • Full response: gửi nguyên lastAssistantMessage (không cắt 800 ký tự)
  • Markdown: mặc định convert MD → Telegram HTML (**bold**, *italic*, `code`, fenced code, link, heading, quote…)
  • Quá 4096 ký tự → tự tách nhiều tin Telegram (ưu tiên ngắt ở newline)
  • macOS / Linux (bash + curl + jq khuyến nghị)
  • Credentials trong ~/.config/agent-cli-telegram/.env (mode 600)
  • Fail-open: thiếu token / mạng lỗi không chặn agent
  • Bỏ qua fire Stop phụ của Grok khi reason != end_turn

Cài nhanh

cd agent-cli-telegram
chmod +x install.sh uninstall.sh bin/telegram-notify.sh
./install.sh

Mặc định cài cả Grok lẫn Claude Code. Chỉ một bên:

./install.sh --grok
./install.sh --claude

Có sẵn token:

./install.sh --token '123:ABC...' --chat-id '987654321'

Tạo bot Telegram

  1. Mở @BotFather → /newbot → lấy token
  2. Mở chat với bot, gửi bất kỳ tin nhắn nào
  3. Lấy chat ID:
curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates" | jq '.result[-1].message.chat.id'
  1. Điền file config (install đã tạo sẵn nếu chưa có):
# ~/.config/agent-cli-telegram/.env
TELEGRAM_BOT_TOKEN=123456789:AAH...
TELEGRAM_CHAT_ID=987654321

Kiểm tra

# Gửi tin test
AGENT_CLI_TELEGRAM_DEBUG=1 agent-cli-telegram-notify <<'JSON'
{
  "hookEventName": "stop",
  "reason": "end_turn",
  "workspaceRoot": "/Users/you/Projects/demo",
  "lastAssistantMessage": "Đã xong task test."
}
JSON

Nếu PATH chưa có ~/.local/bin:

export PATH="$HOME/.local/bin:$PATH"
# hoặc gọi thẳng:
~/.local/bin/agent-cli-telegram-notify

Grok Build

Install ghi hook vào:

~/.grok/hooks/agent-cli-telegram.json

Restart session Grok, hoặc mở /hooks để xác nhận hook đã load.

Hook gọi script khi:

  • Stop — agent xong lượt
  • StopFailure — lỗi API

Claude Code

Install merge vào ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/you/.local/bin/agent-cli-telegram-notify",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Mở session Claude mới để áp dụng.

Tắt tạm thời

Trong shell đang chạy agent:

export TG_ON=0
# hoặc
export TELEGRAM_NOTIFY_DISABLED=1

Gỡ cài

./uninstall.sh              # giữ lại .env
./uninstall.sh --purge-config

Cấu trúc

agent-cli-telegram/
├── bin/telegram-notify.sh      # script gửi Telegram
├── hooks/telegram-notify.json  # template hook Grok
├── claude/settings.fragment.json
├── install.sh
├── uninstall.sh
├── .env.example
└── README.md

Bảo mật

  • Token bot = secret. Không commit .env.
  • Nội dung lastAssistantMessage được gửi lên Telegram — đừng bật nếu prompt/code nhạy cảm.
  • File config mặc định chmod 600.

Biến môi trường

Biến Mô tả
TELEGRAM_BOT_TOKEN Bot token từ BotFather
TELEGRAM_CHAT_ID Chat/user ID nhận tin
TELEGRAM_MESSAGE_CHAR_LIMIT Độ dài tối đa (1–4096, mặc định 4096)
TELEGRAM_PARSE_MODE Mặc định HTML (render Markdown). Tắt: off / plain
TELEGRAM_NOTIFY_DISABLED=1 Tắt hoàn toàn
TG_ON=0 Tắt theo session
AGENT_CLI_TELEGRAM_DEBUG=1 Log debug ra stderr
AGENT_CLI_TELEGRAM_ENV_FILE Đường dẫn .env tùy chỉnh

License

MIT

About

Telegram notifications when Grok/Claude Code agent CLI turns finish (Stop hook)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0