claude-telegram-bot 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.4.2] - 2026-07-14
+### Added
+- 그룹 채팅에서 메시지를 보낸 사람을 `[From: 이름 (@username)]` 형태로 프롬프트에 표시한다(1:1 채팅은
+  한 명뿐이라 표시하지 않음). `busy` 중 쌓인 메시지를 한 번에 합쳐 보내는 큐 병합 시에도 줄마다 발신자를
+  구분해 표기한다 — 이전엔 마지막 발신자만 남아 앞서 온 메시지들의 발신자 정보가 유실됐었다.
+### Fixed
+- `ctb`가 provider를 고를 때 `state.json`의 `provider`(텔레그램 `/provider`로 전환한 값)를 무시하고
+  `config.provider`만 보던 버그. 텔레그램에서 `/provider codex`로 전환해둔 상태에서 `ctb`를 실행하면
+  엉뚱하게 Claude 세션을 resume해 로컬 대화가 텔레그램 쪽 세션과 분리되던 문제였음 — 우선순위를
+  `--provider` → `state.provider` → `config.provider` → `claude`로 수정해 bot.mjs의 `currentProvider()`와
+  동일하게 맞췄다.
+- `ctb` 세션 종료 알림(`notifyTelegram`)이 `allowedChatId`가 배열일 때 `chat_id`에 배열을 그대로 넣어
+  텔레그램 API가 `400 Bad Request`로 거부하던 버그 — 각 chat_id를 순회하며 개별 전송하도록 수정.
+- 레이트리밋으로 메시지가 reserve 큐에 쌓인 상태에서 `/provider`로 다른 provider로 전환해도 큐가 그대로
+  묶여 있던 버그 — 전환 시 예약을 즉시 풀고 새 provider로 큐를 이어서 처리하도록 수정.
+
 ## [0.4.1] - 2026-07-10
 ### Changed
 - `ctb`의 provider 결정 우선순위(`--provider` → `config.provider` → `claude`)를 도움말에 명시했다.

package/README.ko.md

@@ -21,6 +21,47 @@
 Claude 한도 → Codex 폴백 → codex-handoff.md → 다음 Claude 호출
 ```
 
+> ### ⚠️ 의도적으로 원격 코드 실행 도구입니다
+> 텔레그램 메시지가 호스트 머신의 코드 실행으로 이어질 수 있습니다. 처음에는
+> `permissionMode: acceptEdits`로 시작하고, 반드시 `allowedChatId`를 설정하세요. 상시 실행 전에
+> [보안](#보안)을 읽어주세요.
+
+## 3분 빠른 시작
+
+필요한 것: **Node.js 18+**, 설치·로그인된 **Claude Code `claude` CLI**, `@BotFather`에서 받은 텔레그램 봇 토큰.
+
+```sh
+npm i -g claude-telegram-bot
+claude-telegram-bot init ~/botconfigs/my-project
+```
+
+`~/botconfigs/my-project/mybot.json`을 수정합니다.
+
+```json
+{
+  "token": "BOT_TOKEN_FROM_BOTFATHER",
+  "allowedChatId": "",
+  "projectDir": "/ABSOLUTE/PATH/TO/PROJECT",
+  "claudeBin": "/ABSOLUTE/PATH/TO/claude",
+  "permissionMode": "acceptEdits"
+}
+```
+
+처음 한 번 실행해서 chat ID를 확인합니다.
+
+```sh
+claude-telegram-bot ~/botconfigs/my-project/mybot.json
+```
+
+텔레그램 봇에 아무 메시지나 보내면 봇이 `chatId`를 알려줍니다. 그 값을 `allowedChatId`에 넣고 재시작한 뒤, 이렇게 요청해보세요.
+
+```text
+테스트 돌려보고 실패한 부분 요약해줘
+```
+
+설치 없이 시험하려면 `npx claude-telegram-bot init`, `npx claude-telegram-bot`을 사용하면 됩니다.
+Claude 대신(또는 함께) Codex를 쓰려면 [설정](#설정)을 참고하세요.
+
 ## 왜 만들었나
 
 자리를 비운 사이에도 폰으로 빌드를 돌려보거나 간단한 수정을 맡기고 싶을 때가 있습니다. 그렇다고 외부에서 데스크톱에 원격 접속해서 터미널을 여는 건 번거롭죠.
@@ -360,6 +401,16 @@ Claude와 Codex의 안전 설정은 서로 다르며 `/provider` 전환 시 실
 
 보안 이슈는 공개로 올리기보다 GitHub 이슈(민감한 내용은 메인테이너에게 비공개)로 알려주세요.
 
+## 개발
+
+```sh
+npm test
+```
+
+smoke test는 CLI 파일에 `node --check`를 실행하고, 두 바이너리가 버전을 출력하는지 확인합니다. CI는 Node 18, 20, 22에서 같은 검사를 실행합니다.
+
+최근 변경 사항은 [CHANGELOG.md](./CHANGELOG.md)를 참고하세요.
+
 ## 라이선스
 
 MIT © Jongtaek Choi

package/README.md

@@ -32,6 +32,52 @@ It runs as a **background daemon** (launchd), so there's no interactive session
 > A message you send from Telegram is executed as a command on the machine running the bot.
 > With `permissionMode: bypassPermissions`, a one-line message can run **anything** as your user.
 
+## 3-minute quick start
+
+Prerequisites: **Node.js 18+**, the **Claude Code `claude` CLI installed and authenticated**, and a Telegram bot token from `@BotFather`.
+
+```sh
+npm i -g claude-telegram-bot
+claude-telegram-bot init ~/botconfigs/my-project
+```
+
+Edit `~/botconfigs/my-project/mybot.json`:
+
+```json
+{
+  "token": "BOT_TOKEN_FROM_BOTFATHER",
+  "allowedChatId": "",
+  "projectDir": "/ABSOLUTE/PATH/TO/PROJECT",
+  "claudeBin": "/ABSOLUTE/PATH/TO/claude",
+  "permissionMode": "acceptEdits"
+}
+```
+
+Start once to discover your chat ID:
+
+```sh
+claude-telegram-bot ~/botconfigs/my-project/mybot.json
+```
+
+Send any message to the Telegram bot. It replies with your `chatId`. Put that value into `allowedChatId`, restart the bot, then send something useful:
+
+```text
+run the tests and summarize any failures
+```
+
+For a no-install trial, use `npx claude-telegram-bot init` and `npx claude-telegram-bot` instead. To
+run Codex instead of (or alongside) Claude, see [Configuration](#configuration).
+
+## Why this exists
+
+Sometimes you are away from your desk but still want to ask a coding agent to inspect a repo, run
+tests, make a small edit, or prepare a commit. Remote desktop and SSH are heavy for that; a Telegram
+chat is enough.
+
+This project is intentionally small: a CLI/daemon that reuses the `claude` and/or `codex` CLI already
+authenticated on your machine. It is best for a Mac mini, home server, dev box, or personal VPS that
+you already trust.
+
 **Highlights**
 
 - **Zero dependencies** — just Node 18+. No npm install, no supply chain.
@@ -511,6 +557,17 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claudebot.example.pl
 - At least one provider: authenticated Claude CLI or authenticated Codex CLI
 - Optional: Codex CLI for Codex fallback; Ollama and a downloaded model for Ollama mode/fallback
 
+## Development
+
+```sh
+npm test
+```
+
+The smoke test runs `node --check` on the CLI files and verifies both binaries can print their
+version. CI runs the same checks on Node 18, 20, and 22.
+
+See [CHANGELOG.md](./CHANGELOG.md) for recent changes.
+
 ## License
 
 MIT © Jongtaek Choi

package/bot.mjs

@@ -1225,9 +1225,23 @@ async function downloadAttachment(att) {
 }
 
 // ── 텔레그램 메시지 메타데이터 추출 ──────────────────────────────────────
+// 그룹 채팅에서 누가 보냈는지 표시할 때 쓰는 이름 포맷 (buildMsgMeta / drainQueue 공용)
+function formatSender(u) {
+  if (!u) return null;
+  if (u.first_name) return `${u.first_name}${u.username ? ` (@${u.username})` : ""}`;
+  return u.username ? `@${u.username}` : null;
+}
+const isGroupChat = (chat) => chat?.type === "group" || chat?.type === "supergroup";
+
 function buildMsgMeta(msg) {
   const parts = [];
 
+  // 그룹 채팅은 발신자가 여러 명일 수 있으니 표시 (1:1은 한 명뿐이라 생략, 큐 병합 메시지는 줄마다 이미 표기)
+  if (isGroupChat(msg.chat) && !msg._merged) {
+    const sender = formatSender(msg.from);
+    if (sender) parts.push(`[From: ${sender}]`);
+  }
+
   // 포워드 출처 (신규 API: forward_origin, 구버전 폴백: forward_from / forward_from_chat)
   const fo = msg.forward_origin;
   if (fo) {
@@ -1275,6 +1289,16 @@ const pendingPlans = new Map(); // chatId → { sessionId, messageId } — /plan
 const PLAN_PROCEED_PROMPT = "Proceed with the plan you just approved above. Implement it now.";
 let rateLimitTimer = null;  // 리셋 시간에 큐를 드레인하는 타이머
 
+// 한도에 걸린 provider에서 다른 provider로 전환하면 예약을 기다릴 이유가 없다.
+// 기존 실패 메시지를 포함한 대기열을 새 provider로 즉시 이어서 처리한다.
+function resumeQueueAfterProviderSwitch(previousProvider) {
+  if (previousProvider === currentProvider() || (!rateLimitUntil && !rateLimitTimer)) return;
+  if (rateLimitTimer) clearTimeout(rateLimitTimer);
+  rateLimitTimer = null;
+  rateLimitUntil = null;
+  if (msgQueue.length > 0) setImmediate(() => handle(drainQueue()));
+}
+
 // runClaude 결과를 답장으로 변환 — 폴백/큐잉/자동 컴팩션 처리. handle()과 /plan 승인 실행이 공유.
 async function replyWithClaudeResult(chatId, l, prompt, msg, res, started) {
   const secs = Math.round((Date.now() - started) / 1000);
@@ -1479,19 +1503,23 @@ async function handle(msg) {
       return;
     }
     if (arg === "default" || arg === "reset") {
+      const previousProvider = currentProvider();
       state.provider = undefined;
       saveState(state);
       await send(chatId, t(l, "providerReset", DEFAULT_PROVIDER));
+      resumeQueueAfterProviderSwitch(previousProvider);
       return;
     }
     if (!["claude", "codex"].includes(arg)) {
       await send(chatId, t(l, "providerUsage"));
       return;
     }
+    const previousProvider = currentProvider();
     state.provider = arg;
     state.ollamaMode = false;
     saveState(state);
     await send(chatId, t(l, "providerSet", arg));
+    resumeQueueAfterProviderSwitch(previousProvider);
     return;
   }
   if (text === "/model" || text.startsWith("/model ")) {
@@ -1801,11 +1829,14 @@ async function handle(msg) {
 function drainQueue() {
   if (msgQueue.length === 1) return msgQueue.shift().msg;
   const group = msgQueue.splice(0);
+  const groupChat = isGroupChat(group[0].msg.chat);
   const merged = group
     .map((item, i) => {
       const text = item.msg.text || item.msg.caption || "";
       const dt = Math.round((item.receivedAt - group[0].receivedAt) / 1000);
-      return i === 0 ? `[1] ${text}` : `[${i + 1}, +${dt}s] ${text}`;
+      const label = i === 0 ? "[1]" : `[${i + 1}, +${dt}s]`;
+      const sender = groupChat ? formatSender(item.msg.from) : null;
+      return sender ? `${label} ${sender}: ${text}` : `${label} ${text}`;
     })
     .join("\n");
   // 마지막 메시지 필드만 남기면 앞서 온 메시지의 사진/첨부가 유실되므로, 전체 첨부를 순서대로 모아 둠
@@ -1818,6 +1849,8 @@ function drainQueue() {
     ...group[group.length - 1].msg,
     text: merged,
     caption: undefined,
+    // 줄마다 발신자를 이미 표기했으니 buildMsgMeta의 단일 [From: ] 태그(마지막 발신자 기준)는 중복이라 생략
+    _merged: groupChat || undefined,
     _mediaGroup: fileIds.length ? fileIds : undefined,
   };
 }

package/ctb.mjs

@@ -120,11 +120,6 @@ async function main() {
       forwardedArgs.push(arg);
     }
   }
-  const provider = providerOverride || cfg.provider || "claude";
-  if (!["claude", "codex"].includes(provider)) {
-    throw new Error(`Unsupported provider: ${provider} (expected claude or codex)`);
-  }
-
   const dataDir = dirname(configPath);
   const botDir = join(dataDir, ".claude-bot");
   const stateBase = basename(configPath, ".json");
@@ -132,6 +127,18 @@ async function main() {
   const statePath = join(botDir, stateFile);
   const lockPath = join(botDir, "local.lock");
 
+  // 봇이 텔레그램에서 /provider 로 전환했을 수 있으니 state.json 의 provider 를
+  // cfg.provider 보다 우선한다 (bot.mjs의 currentProvider()와 동일한 우선순위).
+  let stateProvider;
+  try {
+    const p = JSON.parse(readFileSync(statePath, "utf8")).provider;
+    if (["claude", "codex"].includes(p)) stateProvider = p;
+  } catch {}
+  const provider = providerOverride || stateProvider || cfg.provider || "claude";
+  if (!["claude", "codex"].includes(provider)) {
+    throw new Error(`Unsupported provider: ${provider} (expected claude or codex)`);
+  }
+
   mkdirSync(botDir, { recursive: true });
   writeFileSync(lockPath, String(process.pid));
   const cleanup = () => { try { unlinkSync(lockPath); } catch {} };
@@ -228,20 +235,24 @@ async function summarizeSession(provider, sid, lang, cfg) {
 async function notifyTelegram(configPath, provider, sessionId) {
   try {
     const cfg = JSON.parse(readFileSync(configPath, "utf8"));
-    if (!cfg.token || !cfg.allowedChatId || cfg.ctbNotify === false) return;
+    // allowedChatId 는 문자열 또는 배열 모두 허용 (bot.mjs의 allowedIds와 동일 규칙).
+    const chatIds = [].concat(cfg.allowedChatId).filter(Boolean).map(String);
+    if (!cfg.token || !chatIds.length || cfg.ctbNotify === false) return;
     const lang = cfg.lang || process.env.LANG || "";
     process.stderr.write("ctb: summarizing session...\n");
     const summary = await summarizeSession(provider, sessionId, lang, cfg);
     if (!summary) { process.stderr.write("ctb: nothing to summarize (SKIP)\n"); return; }
     process.stderr.write(`ctb: sending to Telegram — ${summary}\n`);
     const label = lang.startsWith("ko") ? "[터미널]" : "[local]";
-    const r = await fetch(`https://api.telegram.org/bot${cfg.token}/sendMessage`, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ chat_id: cfg.allowedChatId, text: `💻 ${label} ${summary}` }),
-    });
-    const json = await r.json();
-    if (!json.ok) process.stderr.write(`ctb: Telegram error — ${JSON.stringify(json)}\n`);
+    for (const chatId of chatIds) {
+      const r = await fetch(`https://api.telegram.org/bot${cfg.token}/sendMessage`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ chat_id: chatId, text: `💻 ${label} ${summary}` }),
+      });
+      const json = await r.json();
+      if (!json.ok) process.stderr.write(`ctb: Telegram error — ${JSON.stringify(json)}\n`);
+    }
   } catch (e) {
     process.stderr.write(`ctb: notify error — ${e.message}\n`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-telegram-bot",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Drive Claude Code or Codex from Telegram with persistent sessions, provider switching, and zero runtime dependencies.",
   "type": "module",
   "bin": {
@@ -22,7 +22,9 @@
     "node": ">=18"
   },
   "scripts": {
-    "start": "node bot.mjs"
+    "start": "node bot.mjs",
+    "smoke": "node --check bot.mjs && node --check ctb.mjs && node bot.mjs --version && node ctb.mjs --version",
+    "test": "npm run smoke"
   },
   "keywords": [
     "claude",