Telegram Chat Bot For Claude code

Telegram Chat BotでClaude Codeを操作するプログラムです。

Github: https://github.com/syrnd/claudecode-chatbot.git

概要

Telegram 経由で Claude Code CLI を操作するボットです。

用途

• Telegram でリクエストを送信
• Claude Code がバックグラウンドで開発タスクを実行
• 長時間タスクの状態確認・停滞検知に対応

機能

• ユーザーごとに同時実行タスクは1つまで
• タスクはバックグラウンド実行（Telegram ポーリングをブロックしない）
• タスク状態は tasks/ ディレクトリにファイル永続化

実行健全性の判定

• active: 最近アクティビティあり

• quiet: しばらくアクティビティなし

• stalled: 長時間アクティビティなし（停滞の疑い）

• 停滞検知時の通知は1回のみ（通知スパム防止）

Telegram コマンド

• /start — ウェルカムメッセージを表示
• /help — 利用可能なコマンド一覧を表示
• /status — 現在のタスク状態を確認（実行時間・進捗・健全性）
• /logs [n] — 最近 n 件のタスクログを表示（デフォルト 8、最大 50）
• /cancel — 実行中のタスクをキャンセル
• /reset — Claude セッションをリセット（※先にタスクをキャンセルする必要あり）
• /model [alias] — モデルの確認・切替（略称：sonnet / opus / haiku）
• /models — 利用可能なモデル一覧（InlineKeyboard で選択）
• /workdir [path] — 作業ディレクトリの確認・切替（許可されたパスプレフィックス内のみ）
• /ls — プロジェクトディレクトリを一覧表示（タップで切替）
• /history [n] — 最近 n 件のタスク履歴を表示（デフォルト 5、最大 20）

※ テキストメッセージを送信すると、新しいタスクとして Claude Code に送られます。

ステータス

メインステータス

• queued: キュー待ち
• running: 実行中
• done: 完了
• error: エラー
• cancelled: キャンセル済み
• timeout: タイムアウト

健全性（running 時のサブステータス）

• active: 最近アクティビティあり
• quiet: しばらくアクティビティなし
• stalled: 長時間アクティビティなし（停滞の疑い、確定ではない）

ローカルファイル

• bot.py — メインプログラム
• claudecode-chatbot.service — systemd サービス定義
• .env.example — 環境変数テンプレート
• sessions.json — Claude セッション永続化
• tasks/ — タスク状態とログ

環境変数

必須

• TELEGRAM_BOT_TOKEN

任意

• ALLOWED_USER_IDS — 許可するユーザーID（カンマ区切り）
• CLAUDE_CMD — Claude Code CLI パス
• CLAUDE_TIMEOUT — タスクの最大実行時間（秒、デフォルト 3600）
• MAX_CONCURRENT_TASKS — 最大同時実行タスク数（デフォルト 2）
• TASK_QUIET_AFTER — quiet 判定閾値（秒、デフォルト 180）
• TASK_STALLED_AFTER — stalled 判定閾値（秒、デフォルト 480）
• STALL_CHECK_INTERVAL — stalled チェック間隔（秒、デフォルト 60）
• TASK_LOG_RETENTION_DAYS — ログ保持日数（デフォルト 7）
• ALLOWED_WORKDIR_PREFIX — 許可する作業ディレクトリプレフィックス（デフォルト /home/sikim/project）

※ 詳細は .env.example を参照

起動・再起動

Python コードや .env のみ変更した場合

sudo systemctl restart claudecode-chatbot.service