Claude Code 작업 완료 알림을 텔레그램으로 받기

글쓴이 /

TL;DR

  • Claude Code로 장시간 작업 시 화면 앞에서 기다릴 필요 없음
  • 작업 완료나 입력 대기 시 텔레그램으로 즉시 알림
  • 5분 설정으로 개발 생산성 크게 향상
  • GitHub: greeun/notify-telegram

문제: Claude Code 앞에서 기다리는 시간

Claude Code는 강력한 AI 코딩 에이전트다. 복잡한 리팩토링, 테스트 작성, 버그 수정 등을 자율적으로 수행한다. 하지만 한 가지 불편한 점이 있다.

작업이 끝날 때까지 화면을 지켜봐야 한다.

대규모 코드베이스 분석이나 복잡한 작업은 수 분에서 수십 분이 걸린다. 그 동안 다른 일을 하고 싶지만, 언제 끝날지 몰라 계속 터미널을 확인하게 된다. 특히 Claude가 추가 정보를 요청하며 대기 중일 때, 그걸 놓치면 작업이 멈춰버린다.

해결: 텔레그램 알림 스킬

이 문제를 해결하기 위해 telegram-notifier 스킬을 만들었다.

기존 방식 워크플로우
❌ 기존 방식
알림 적용 후 워크플로우
✅ 알림 적용 후

Claude Code의 Hook 시스템을 활용해 다음 상황에서 텔레그램 알림을 보낸다.

알림 유형별 흐름도
알림 유형별 흐름
상황 알림 내용
작업 완료 “Task completed” – 요청한 작업이 끝났을 때
사용자 입력 대기 “Waiting for input” – 추가 정보가 필요할 때
오류 발생 “Error occurred” – 문제가 생겼을 때

시스템 구조

시스템 아키텍처 다이어그램
Claude Code → Hook → Telegram API → 사용자

왜 텔레그램인가?

알림 채널로 텔레그램을 선택한 이유

  1. 즉시성: 푸시 알림이 즉각적으로 도착
  2. 무료: 봇 API 사용에 비용 없음
  3. 크로스 플랫폼: 데스크톱, 모바일 어디서든 확인
  4. 간단한 API: curl 한 줄로 메시지 전송 가능
  5. 프라이버시: 개인 채팅으로 나만 볼 수 있음

실제 효용

1. 멀티태스킹이 가능해진다

Claude Code에 큰 작업을 맡기고 다른 일을 할 수 있다.

  • 다른 프로젝트 코드 리뷰
  • 문서 작성
  • 회의 참석
  • 커피 마시기

알림이 오면 그때 돌아오면 된다.

2. 입력 대기를 놓치지 않는다

Claude가 “이 파일을 수정해도 될까요?” 같은 확인을 요청할 때, 바로 알 수 있다. 더 이상 작업이 멈춘 채 방치되는 일이 없다.

3. 야간/장시간 작업에 유용

대규모 리팩토링이나 마이그레이션처럼 오래 걸리는 작업을 시작하고 자리를 비울 수 있다. 완료되면 폰으로 알림이 온다.

설정 방법

1단계: 텔레그램 봇 생성

  1. Telegram에서 @BotFather 검색
  2. /newbot 명령으로 봇 생성
  3. Bot Token 복사

2단계: Chat ID 확인

  1. 생성한 봇에게 아무 메시지 발송
  2. 브라우저에서 https://api.telegram.org/bot<TOKEN>/getUpdates 접속
  3. JSON에서 chat id 확인

3단계: 환경 변수 설정

# ~/.zshrc에 추가
export TELEGRAM_BOT_TOKEN="your_token"
export TELEGRAM_CHAT_ID="your_chat_id"

4단계: 스킬 설치 및 Hook 설정

스킬을 ~/.claude/skills/telegram-notifier/에 설치하고, ~/.claude/settings.json에 Hook을 추가한다.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/skills/telegram-notifier/scripts/send_telegram.py \"$CLAUDE_NOTIFICATION_TITLE\" \"$CLAUDE_NOTIFICATION_MESSAGE\""
          }
        ]
      }
    ]
  }
}

5단계: 테스트

python3 ~/.claude/skills/telegram-notifier/scripts/send_telegram.py "테스트" "설정 완료!"

텔레그램으로 메시지가 오면 성공이다.

기술 구현

스킬 구조는 단순하다.

telegram-notifier/
├── SKILL.md              # 스킬 정의
├── scripts/
│   └── send_telegram.py  # 발송 스크립트
└── references/
    └── setup-guide.md    # 설정 가이드

핵심인 send_telegram.py는 표준 라이브러리만 사용해 외부 의존성이 없다.

import urllib.request
import urllib.parse

def send_telegram(title, message):
    url = f"https://api.telegram.org/bot{token}/sendMessage"
    data = urllib.parse.urlencode({
        "chat_id": chat_id,
        "text": f"🤖 *Claude Code*\n\n*{title}*\n{message}",
        "parse_mode": "Markdown"
    }).encode()
    urllib.request.urlopen(url, data)

마치며

작은 자동화가 큰 차이를 만든다.

Claude Code는 강력하지만, 그 힘을 제대로 활용하려면 작업을 맡기고 기다리는 것이 가능해야 한다. 텔레그램 알림 하나로 Claude Code 사용 경험이 훨씬 편해졌다.

GitHub에 공개해두었으니 필요하면 사용해보시길.

Repository: https://github.com/greeun/notify-telegram

위로 스크롤