claude-telegram-bot 0.2.6 → 0.3.0

package/README.ko.md

@@ -2,6 +2,10 @@
 
 **한국어** · [English](./README.md)
 
+[![npm version](https://img.shields.io/npm/v/claude-telegram-bot.svg)](https://www.npmjs.com/package/claude-telegram-bot)
+[![npm downloads](https://img.shields.io/npm/dm/claude-telegram-bot.svg)](https://www.npmjs.com/package/claude-telegram-bot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 텔레그램으로 메시지를 보내면, 집이나 서버에 켜둔 Claude Code가 작업하고 결과를 다시 텔레그램으로 돌려주는 봇입니다.
 
 ```
@@ -64,9 +68,11 @@ OpenClaw처럼 웹 UI까지 갖춘 구성을 써봤다면, 이 프로젝트는
 **npx로 바로 실행**
 
 ```sh
-npx claude-telegram-bot init        # 현재 폴더에 config.json 생성
-# config.json 편집 (token, projectDir 등)
-npx claude-telegram-bot             # config.json 으로 실행
+npx claude-telegram-bot init              # 현재 폴더에 config.json 생성
+npx claude-telegram-bot init mybot.json   # 파일명 직접 지정도 가능
+# 설정 편집 (token, projectDir 등)
+npx claude-telegram-bot                   # config.json 으로 실행
+npx claude-telegram-bot mybot.json        # 또는 경로를 직접 전달
 ```
 
 **전역 설치 (상시 가동에 권장)**
@@ -74,9 +80,10 @@ npx claude-telegram-bot             # config.json 으로 실행
 ```sh
 npm i -g claude-telegram-bot
 
-claude-telegram-bot init ~/botconfigs/myproj    # 해당 경로에 config.json 생성
-# config.json 편집
-claude-telegram-bot ~/botconfigs/myproj/config.json
+claude-telegram-bot init ~/botconfigs/myproj              # config.json 생성
+claude-telegram-bot init ~/botconfigs/myproj/mybot.json   # 또는 파일명 지정
+# 설정 편집
+claude-telegram-bot ~/botconfigs/myproj/mybot.json
 ```
 
 > **설정 파일은 git에 올리지 마세요.** config 파일에는 봇 토큰이 들어 있습니다. git 레포 안에 둔다면 `config.json`, `state*.json`, `attachments/`를 그 프로젝트의 `.gitignore`에 추가하세요. 이 레포는 해당 패턴을 이미 무시하므로 `claudebot.config.json` 같은 이름도 안전하지만, 다른 프로젝트는 직접 지정해야 합니다.
@@ -110,13 +117,17 @@ claude-telegram-bot ~/botconfigs/myproj/config.json
    - `테스트 돌려보고 통과하면 커밋하고 push 해줘`
    - `api.ts 에 에러 핸들링 추가해줘`
 
-명령어: `/new`(맥락 초기화) · `/cron`(예약 작업 보기·추가·삭제) · `/restart`(문법 검사 후 재시작) · `/status`(봇 상태·버전) · `/model`(모델 보기·전환) · `/id`(채팅 ID 확인) · `/help`(도움말)
+명령어: `/new`(맥락 초기화) · `/stop`(작업 중단; `--reset`으로 세션도 롤백) · `/cron`(예약 작업 보기·추가·삭제) · `/restart`(문법 검사 후 재시작) · `/status`(봇 상태·버전) · `/model`(모델 보기·전환) · `/id`(채팅 ID 확인) · `/help`(도움말)
+
+> **`/stop`** 은 실행 중인 Claude 프로세스를 즉시 종료하고 대기 중인 메시지 큐도 비웁니다. `--reset`을 붙이면 세션을 작업 시작 이전 상태로 되돌려 중단된 작업이 대화 맥락에 남지 않습니다.
 
 > **`/restart`** 는 먼저 `bot.mjs` 에 `node --check` 를 돌려 **문법 오류가 있으면 재시작을 취소**합니다(잘못된 수정이 봇을 크래시 루프에 빠뜨리는 것 방지). 통과하면 프로세스를 종료하고, 다시 띄우는 건 프로세스 관리자에게 맡깁니다. [launchd 설정](#상시-실행-launchd)(`KeepAlive`)이면 바로 동작하고, 관리자 없이 `node bot.mjs` 로만 돌리면 그냥 멈춥니다. 재시작 후 대화 세션은 `state.json` 의 ID로 이어집니다.
 
 ## 사용 메모
 
 - **세션 유지** — 대화는 `--resume`으로 자동으로 이어집니다. 마지막 세션 ID가 `state.json`에 저장되므로 봇을 재시작해도 맥락이 남습니다. 새로 시작하려면 `/new`.
+- **메시지 큐** — 작업 중에 새 메시지가 오면 버리지 않고 큐에 쌓아둡니다. 작업이 끝나면 대기 중인 메시지를 모두 하나의 프롬프트로 합쳐서 처리합니다(예: "A 해줘" → "아니다 B 해줘"를 한 번에 처리). `/stop`으로 실행 중인 작업과 큐를 동시에 취소할 수 있습니다.
+- **모델 권유** — 봇이 Claude에게 현재 모델을 알려줍니다. 질문 난이도가 현재 모델 수준을 넘는다고 판단되면 답변 끝에 전환 권유 한 줄이 붙습니다(예: 💡 `/model sonnet`). `/model <이름>`으로 전환(`haiku`, `sonnet`, `opus`, `fable`, 또는 전체 모델 ID) — `state.json`에 저장돼 재시작 후에도 유지됩니다.
 - **간결한 답변** — 텔레그램에 맞게 짧게 답하도록 시스템 프롬프트가 기본으로 붙습니다. 바꾸려면 `appendSystemPrompt`에 직접 넣으세요 (빈 문자열이면 끔).
 - **언어** — 봇 자체 문구(`/help`, 명령 메뉴, 상태 메시지)는 **기본 영어**, 텔레그램이 한국어인 사용자에겐 한국어로 나옵니다. `lang`(`"en"`/`"ko"`)으로 고정할 수 있습니다. Claude의 실제 답변은 **사용자가 쓴 언어**를 따라갑니다. `/` 명령 메뉴는 `setMyCommands`로 언어별 등록됩니다.
 - **서식 변환** — 답변의 마크다운(굵게·코드·표 등)을 텔레그램 HTML로 바꿔 보냅니다. 변환이 깨지는 경우엔 평문으로 다시 보냅니다.

package/README.md

@@ -2,11 +2,15 @@
 
 [한국어](./README.ko.md) · **English**
 
+[![npm version](https://img.shields.io/npm/v/claude-telegram-bot.svg)](https://www.npmjs.com/package/claude-telegram-bot)
+[![npm downloads](https://img.shields.io/npm/dm/claude-telegram-bot.svg)](https://www.npmjs.com/package/claude-telegram-bot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 **A zero-dependency, single-file, daemonized Claude Code bot — no Bun, no Python, no open session.**
 
 A tiny bridge that takes your Telegram messages, runs `claude -p` (Claude Code headless mode)
 in a project folder, and sends the result back to the chat. One `.mjs` file on Node 18+ built-ins —
-nothing to `npm install`, nothing to audit but ~400 readable lines.
+nothing to `npm install`, nothing to audit but under 1 000 readable lines.
 
 ```
 [you] → Telegram → bot.mjs → claude -p (config.projectDir) → result → Telegram
@@ -114,9 +118,11 @@ Prerequisites: **Node 18+** and the **`claude` CLI installed and authenticated**
 **Option A — npx (no install)**
 
 ```sh
-npx claude-telegram-bot init        # writes ./config.json
-# edit config.json (token, projectDir, …)
-npx claude-telegram-bot             # runs ./config.json
+npx claude-telegram-bot init             # writes ./config.json
+npx claude-telegram-bot init mybot.json  # or pick your own filename
+# edit the config (token, projectDir, …)
+npx claude-telegram-bot                  # runs ./config.json
+npx claude-telegram-bot mybot.json       # or pass the path directly
 ```
 
 **Option B — global install (recommended for an always-on daemon)**
@@ -124,9 +130,10 @@ npx claude-telegram-bot             # runs ./config.json
 ```sh
 npm i -g claude-telegram-bot
 
-claude-telegram-bot init ~/botconfigs/myproj    # writes ~/botconfigs/myproj/config.json
-# edit that config.json (token, projectDir, …)
-claude-telegram-bot ~/botconfigs/myproj/config.json
+claude-telegram-bot init ~/botconfigs/myproj           # writes ~/botconfigs/myproj/config.json
+claude-telegram-bot init ~/botconfigs/myproj/mybot.json  # or a custom filename
+# edit the config (token, projectDir, …)
+claude-telegram-bot ~/botconfigs/myproj/mybot.json
 ```
 
 Run several projects/personas by making one config file each and passing its path —
@@ -154,7 +161,11 @@ auth layer.)
 - `run the solver tests and commit + push if they pass`
 - `add an edge case to solve-2nd-floor-edges.ts`
 
-Commands: `/new` (reset context / new session) · `/cron` (list / add / remove scheduled tasks) · `/restart` (syntax-check & restart the bot) · `/status` (bot status & version) · `/model` (view / switch the model) · `/id` (show chat ID) · `/help`.
+Commands: `/new` (reset context / new session) · `/stop` (stop current task; `--reset` to also roll back the session) · `/cron` (list / add / remove scheduled tasks) · `/restart` (syntax-check & restart the bot) · `/status` (bot status & version) · `/model` (view / switch the model) · `/id` (show chat ID) · `/help`.
+
+> **`/stop`** kills the running Claude process immediately and clears any queued messages.
+> Add `--reset` to also restore the session to the state it was in *before* the task started,
+> so the conversation history doesn't include the interrupted work.
 
 > **`/restart`** runs `node --check` on `bot.mjs` first and **aborts the restart if it has a syntax
 > error** (so a bad edit can't crash-loop the bot), then exits — relying on a process supervisor
@@ -211,6 +222,8 @@ your launchd plist points them.
   absolute path is handed to Claude (caption included as the message). Images can be opened with Read.
 - **Sessions**: conversations resume automatically (`--resume`); the last session id is saved in
   `state.json`, so context survives restarts. Use `/new` to start fresh.
+- **Message queue**: if you send a message while a task is running, it is queued (not dropped). When the task finishes, all queued messages are merged into a single prompt so Claude can resolve corrections and follow-ups in one pass (e.g. "do X" then "never mind, do Y" → handled together). Use `/stop` to cancel the running task and discard the queue.
+- **Model hint**: the bot tells Claude which model it is running as. If Claude judges a question to be beyond its current tier, it appends a one-line suggestion at the end of the reply (e.g. 💡 `/model sonnet`). Switch with `/model <name>` — `haiku`, `sonnet`, `opus`, `fable`, or a full model id. The choice persists in `state.json` across restarts.
 
 ### Scheduled tasks (cron)
 

package/bot.mjs

@@ -13,8 +13,8 @@
 // 사용자 대상 문구는 영어 기본 + 한국어(STR 테이블). 언어는 텔레그램 from.language_code 로
 // 자동 판별하고, cfg.lang 을 주면 그 언어로 고정함. 콘솔/CLI 출력은 영어 단일.
 
-import { basename, dirname, join } from "node:path";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 
 import dns from "node:dns";
 import { fileURLToPath } from "node:url";
@@ -57,7 +57,8 @@ Requires: the claude CLI installed and authenticated on the host.`);
     process.exit(0);
   }
   if (a === "init") {
-    const target = join(process.argv[3] || process.cwd(), "config.json");
+    const arg = process.argv[3];
+    const target = arg?.endsWith(".json") ? resolve(arg) : join(arg || process.cwd(), "config.json");
     if (existsSync(target)) {
       console.error(`Already exists: ${target}`);
       process.exit(1);
@@ -126,6 +127,7 @@ const STR = {
       `${cfg.name || "Claude Code Telegram bot"}\n\n` +
       "• Just send a message and Claude works in the project.\n" +
       "• /new — reset conversation context (new session)\n" +
+      "• /stop — stop the current task · /stop --reset to also roll back the session\n" +
       "• /cron — list tasks · /cron add <natural language> to add · /cron rm <id> to remove\n" +
       "• /restart — restart the bot (after a syntax check)\n" +
       "• /status — bot status & version\n" +
@@ -134,6 +136,11 @@ const STR = {
       `\nWorking dir: ${cfg.projectDir}\nPermission mode: ${cfg.permissionMode}`,
     newSession: "🆕 Started a new conversation (previous context cleared).",
     busy: "⏳ A previous task is still running. Please try again when it finishes.",
+    queued: (n) => `⏳ Queued (#${n}). Will run when the current task finishes.`,
+    stopOk: "🛑 Task stopped.",
+    stopReset: "🛑 Task stopped and session rolled back to before the task.",
+    stopNoop: "No task is running.",
+    localBusy: "💻 A local `ctb claude` session is active. Send a message when it's done.",
     needChatId: (id) => `Add this chat ID to "allowedChatId" in config.json:\n${id}`,
     cronEmpty:
       "No scheduled tasks yet.\nAdd one in plain language, e.g. `/cron add summarize open issues every weekday at 9am`.",
@@ -181,6 +188,7 @@ const STR = {
       `${cfg.name || "Claude Code 텔레그램 봇"}\n\n` +
       "• 그냥 메시지를 보내면 Claude가 프로젝트에서 작업합니다.\n" +
       "• /new — 대화 맥락 초기화 (새 세션)\n" +
+      "• /stop — 진행 중인 작업 중단 · /stop --reset 으로 세션도 되돌리기\n" +
       "• /cron — 예약 작업 보기 · /cron add <자연어>로 추가 · /cron rm <번호>로 삭제\n" +
       "• /restart — 봇 재시작 (문법 검사 후 안전하게)\n" +
       "• /status — 봇 상태·버전 보기\n" +
@@ -189,6 +197,11 @@ const STR = {
       `\n작업 폴더: ${cfg.projectDir}\n권한 모드: ${cfg.permissionMode}`,
     newSession: "🆕 새 대화를 시작합니다 (이전 맥락 초기화).",
     busy: "⏳ 이전 작업이 아직 진행 중입니다. 끝나면 다시 보내주세요.",
+    queued: (n) => `⏳ 대기열에 추가됐습니다 (${n}번째). 현재 작업이 끝나면 자동으로 실행됩니다.`,
+    stopOk: "🛑 작업을 중단했습니다.",
+    stopReset: "🛑 작업을 중단하고 세션을 작업 이전으로 되돌렸습니다.",
+    stopNoop: "실행 중인 작업이 없습니다.",
+    localBusy: "💻 로컬 `ctb claude` 세션이 활성화되어 있습니다. 종료 후 메시지를 보내주세요.",
     needChatId: (id) => `이 채팅 ID를 config.json 의 allowedChatId 에 넣으세요:\n${id}`,
     cronEmpty:
       "등록된 예약 작업이 없습니다.\n`/cron add 매일 아침 9시에 …` 처럼 자연어로 추가해 보세요.",
@@ -237,12 +250,13 @@ const t = (l, key, ...a) => {
 };
 
 // /model 에서 보여줄 추천 별칭(claude CLI 가 별칭·전체 모델 ID 모두 허용).
-const MODEL_SUGGESTIONS = ["opus", "sonnet", "haiku"];
+const MODEL_SUGGESTIONS = ["fable", "opus", "sonnet", "haiku"];
 
 // /(슬래시) 자동완성 메뉴용 명령 목록 (언어별). setMyCommands 로 등록.
 const COMMANDS = {
   en: [
     { command: "new", description: "Reset context (new session)" },
+    { command: "stop", description: "Stop the current task (--reset to roll back session)" },
     { command: "cron", description: "List / add / remove scheduled tasks" },
     { command: "restart", description: "Restart the bot (after syntax check)" },
     { command: "status", description: "Bot status / version" },
@@ -252,6 +266,7 @@ const COMMANDS = {
   ],
   ko: [
     { command: "new", description: "대화 맥락 초기화 (새 세션)" },
+    { command: "stop", description: "작업 중단 (--reset 으로 세션 되돌리기)" },
     { command: "cron", description: "예약 작업 보기·추가·삭제" },
     { command: "restart", description: "봇 재시작 (문법 검사 후)" },
     { command: "status", description: "봇 상태·버전 보기" },
@@ -261,6 +276,23 @@ const COMMANDS = {
   ],
 };
 
+// ── 로컬 세션 lock ────────────────────────────────────────────────────────
+// ctb claude 실행 시 .claude-bot/local.lock (PID) 을 생성하고 종료 시 삭제.
+// 봇은 claude 실행 전 이 파일을 확인해 동시 실행을 방지한다.
+// PID 가 이미 종료된 경우(stale lock) 자동 제거 후 진행.
+const LOCAL_LOCK_PATH = join(BOT_DIR, "local.lock");
+function checkLocalLock() {
+  if (!existsSync(LOCAL_LOCK_PATH)) return false;
+  try {
+    const pid = parseInt(readFileSync(LOCAL_LOCK_PATH, "utf8"), 10);
+    process.kill(pid, 0); // throws if process is dead
+    return true; // lock is valid
+  } catch {
+    try { unlinkSync(LOCAL_LOCK_PATH); } catch {} // stale — remove
+    return false;
+  }
+}
+
 // ── 상태 (세션 이어가기용) ────────────────────────────────────────────────
 function loadState() {
   // 새 경로(.claude-bot/) 우선, 없으면 구버전 루트 경로로 폴백(이주 실패 시 안전망).
@@ -395,7 +427,7 @@ function runClaude(prompt, sessionId, opts = {}) {
       "This reply is delivered over Telegram. Be concise — short paragraphs and lists, no filler intro/summary, avoid large tables. Reply in the user's language.";
     // opts.modelHint: 현재 모델을 주입 → 답변 끝에 상위 모델 권유 제안(판단은 Claude 본인)
     const modelHint = opts.modelHint
-      ? `Current model: ${model || "claude (default)"}. Model tiers (low→high): haiku → sonnet → opus. If this question seems to require more capability than the current model, append one short line at the very end of your reply: 💡 \`/model sonnet\` (or \`/model opus\`) for a stronger answer. Omit the suggestion for simple questions.`
+      ? `Current model: ${model || "claude (default)"}. Model tiers (low→high): haiku → sonnet → opus → fable. If this question seems to require more capability than the current model, append one short line at the very end of your reply: 💡 \`/model sonnet\` (or \`/model opus\`, \`/model fable\`) for a stronger answer. Omit the suggestion for simple questions.`
       : null;
     // 페르소나(cfg.persona) + 간결 지침 + 모델 힌트를 함께 주입 → 멀티 봇(역할별) 운영용
     const appendSys = [cfg.persona, brevity, modelHint].filter(Boolean).join("\n\n");
@@ -407,6 +439,7 @@ function runClaude(prompt, sessionId, opts = {}) {
       cwd: cfg.projectDir,
       env: { ...process.env, ...(cfg.env || {}) },
     });
+    if (opts.trackChild) currentChild = child; // /stop 에서 kill 가능하도록 노출
 
     let out = "",
       err = "";
@@ -416,10 +449,12 @@ function runClaude(prompt, sessionId, opts = {}) {
     child.stderr.on("data", (d) => {
       err += d;
     });
-    child.on("error", (e) =>
-      resolve({ ok: false, text: `Failed to start claude: ${e.message}` }),
-    );
+    child.on("error", (e) => {
+      currentChild = null;
+      resolve({ ok: false, text: `Failed to start claude: ${e.message}` });
+    });
     child.on("close", (code) => {
+      currentChild = null;
       try {
         const j = JSON.parse(out);
         resolve({
@@ -502,7 +537,7 @@ let schedule = buildSchedule();
 // 예약 작업은 사용자 대화 맥락을 오염시키지 않도록 항상 새 세션으로 독립 실행하고,
 // 결과를 allowedChatId 로 보낸다. busy 락을 공유해 사용자 요청과 직렬화됨.
 async function runScheduled(job) {
-  if (busy) {
+  if (busy || checkLocalLock()) {
     console.warn(`Skipped scheduled job (busy): ${job.cron} — ${String(job.prompt).slice(0, 40)}`);
     return;
   }
@@ -674,6 +709,11 @@ async function downloadAttachment(att) {
 
 // ── 메시지 처리 ───────────────────────────────────────────────────────────
 let busy = false;
+const msgQueue = []; // { msg, receivedAt } — busy 중 수신 메시지 대기열
+let currentChild = null;  // 실행 중인 claude child process (/stop 용)
+let currentTyping = null; // 타이핑 인터벌 (/stop 시 정리용)
+let prevSessionId;        // /stop --reset 복원 대상
+let stopping = false;     // /stop 처리 중 오류 메시지 억제 플래그
 
 async function handle(msg) {
   const chatId = msg.chat?.id;
@@ -764,16 +804,37 @@ async function handle(msg) {
     await send(chatId, t(l, "newSession"));
     return;
   }
+  if (text === "/stop" || text.startsWith("/stop ")) {
+    if (!busy || !currentChild) {
+      await send(chatId, t(l, "stopNoop"));
+      return;
+    }
+    const reset = text.includes("--reset");
+    stopping = true;
+    msgQueue.length = 0; // 대기 메시지도 취소
+    currentChild.kill();
+    if (reset) {
+      state.sessionId = prevSessionId;
+      saveState(state);
+    }
+    await send(chatId, t(l, reset ? "stopReset" : "stopOk"));
+    return;
+  }
 
   if (busy) {
-    await send(chatId, t(l, "busy"));
+    msgQueue.push({ msg, receivedAt: Date.now() });
+    await send(chatId, t(l, "queued", msgQueue.length));
+    return;
+  }
+  if (checkLocalLock()) {
+    await send(chatId, t(l, "localBusy"));
     return;
   }
   busy = true;
   await tg("sendChatAction", { chat_id: chatId, action: "typing" });
   const started = Date.now();
   // 긴 작업 동안 타이핑 표시 유지
-  const typing = setInterval(
+  currentTyping = setInterval(
     () =>
       tg("sendChatAction", { chat_id: chatId, action: "typing" }).catch(
         () => {},
@@ -792,7 +853,8 @@ async function handle(msg) {
         await send(chatId, t(l, "attachFail", e.message));
       }
     }
-    const res = await runClaude(prompt, state.sessionId, { modelHint: true });
+    prevSessionId = state.sessionId; // /stop --reset 복원 대상 저장
+    const res = await runClaude(prompt, state.sessionId, { modelHint: true, trackChild: true });
     if (res.sessionId) {
       state.sessionId = res.sessionId;
       saveState(state);
@@ -801,15 +863,32 @@ async function handle(msg) {
     const footer = res.ok
       ? `\n\n— ${secs}s${res.cost ? ` · $${res.cost.toFixed(4)}` : ""}`
       : "";
-    await send(chatId, (res.ok ? res.text : `⚠️ ${res.text}`) + footer);
+    if (!stopping) await send(chatId, (res.ok ? res.text : `⚠️ ${res.text}`) + footer);
   } catch (e) {
-    await send(chatId, t(l, "botError", e.message));
+    if (!stopping) await send(chatId, t(l, "botError", e.message));
   } finally {
-    clearInterval(typing);
+    clearInterval(currentTyping);
+    currentTyping = null;
+    stopping = false;
     busy = false;
+    if (msgQueue.length > 0) setImmediate(() => handle(drainQueue()));
   }
 }
 
+// 큐 전체를 꺼내 하나의 메시지로 합침. 여러 개면 번호+경과시간 붙여 병합 → Claude가 맥락 일괄 파악.
+function drainQueue() {
+  if (msgQueue.length === 1) return msgQueue.shift().msg;
+  const group = msgQueue.splice(0);
+  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}`;
+    })
+    .join("\n");
+  return { ...group[group.length - 1].msg, text: merged, caption: undefined };
+}
+
 // ── 롱폴링 루프 ───────────────────────────────────────────────────────────
 async function main() {
   console.log("Bot started. Polling Telegram...");

package/ctb.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// ctb — short-form CLI for claude-telegram-bot
+//
+// ctb [config.json] [...claude args]   Run Claude, resuming the shared Telegram session
+// ctb bot [config.json]                Start the Telegram bot daemon (delegates to bot.mjs)
+// ctb init [dir]                       Create a config.json template
+// ctb --help | --version
+//
+// config.json is optional. A bare name like "planner.json" resolves relative to the
+// package directory (where bot configs typically live alongside bot.mjs).
+// Absolute or explicitly relative paths (/ or ./) resolve as-is.
+//
+// While Claude runs, .claude-bot/local.lock (PID) is created so the bot defers
+// incoming Telegram messages until the local session ends.
+
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const a = args[0];
+
+const VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(HERE, "package.json"), "utf8")).version;
+  } catch {
+    return "?";
+  }
+})();
+
+function runBot(botArgs) {
+  const child = spawn(process.execPath, [join(HERE, "bot.mjs"), ...botArgs], {
+    stdio: "inherit",
+  });
+  child.on("close", (code) => process.exit(code ?? 0));
+}
+
+function resolveConfig(arg) {
+  if (!arg) return process.env.BOT_CONFIG || join(HERE, "config.json");
+  // Absolute or explicitly relative path → use as-is
+  if (arg.startsWith("/") || arg.startsWith("./") || arg.startsWith("../"))
+    return arg;
+  // Bare name (e.g. "planner.json") → relative to package dir
+  return join(HERE, arg);
+}
+
+function main() {
+  if (a === "-h" || a === "--help") {
+    console.log(
+      `ctb v${VERSION} — claude-telegram-bot short CLI\n\n` +
+      `Usage:\n` +
+      `  ctb [config.json] [...args]   Resume Telegram session and run Claude\n` +
+      `  ctb bot [config.json]         Start the Telegram bot daemon\n` +
+      `  ctb init [dir]                Create a config.json template\n` +
+      `  ctb --help | --version\n\n` +
+      `config.json defaults to $BOT_CONFIG or the package's own config.json.\n` +
+      `A bare name like "planner.json" resolves relative to the package directory.\n\n` +
+      `Examples:\n` +
+      `  ctb                           Interactive Claude, continuing the Telegram session\n` +
+      `  ctb -p "what did we do?"      Headless Claude with session context\n` +
+      `  ctb planner.json              Resume planner persona session interactively\n` +
+      `  ctb planner.json -p "..."     Headless with planner session\n` +
+      `  ctb bot                       Start the bot with default config\n` +
+      `  ctb bot planner.json          Start the bot with planner config`,
+    );
+    process.exit(0);
+  }
+
+  if (a === "-v" || a === "--version") {
+    console.log(VERSION);
+    process.exit(0);
+  }
+
+  if (a === "init") {
+    runBot(args);
+    return;
+  }
+
+  if (a === "bot") {
+    runBot(args.slice(1));
+    return;
+  }
+
+  // Run Claude, resuming the bot's session
+  const looksLikeConfig = a && a.endsWith(".json");
+  const configPath = resolveConfig(looksLikeConfig ? a : undefined);
+  const claudeArgs = looksLikeConfig ? args.slice(1) : args;
+
+  const dataDir = dirname(configPath);
+  const botDir = join(dataDir, ".claude-bot");
+  const stateBase = basename(configPath, ".json");
+  const stateFile = stateBase === "config" ? "state.json" : `${stateBase}.state.json`;
+  const statePath = join(botDir, stateFile);
+  const lockPath = join(botDir, "local.lock");
+
+  mkdirSync(botDir, { recursive: true });
+  writeFileSync(lockPath, String(process.pid));
+  const cleanup = () => { try { unlinkSync(lockPath); } catch {} };
+  process.on("exit", cleanup);
+  process.on("SIGINT", () => { cleanup(); process.exit(130); });
+  process.on("SIGTERM", () => { cleanup(); process.exit(143); });
+
+  let sessionId;
+  try {
+    sessionId = JSON.parse(readFileSync(statePath, "utf8")).sessionId;
+  } catch {}
+
+  const finalArgs = sessionId ? ["--resume", sessionId, ...claudeArgs] : claudeArgs;
+  if (sessionId) process.stderr.write(`Resuming session: ${sessionId}\n`);
+
+  const child = spawn("claude", finalArgs, { stdio: "inherit" });
+  child.on("close", (code) => process.exit(code ?? 0));
+}
+
+main();

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "claude-telegram-bot",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Drive Claude Code from Telegram — messages run headless `claude -p` in a project dir and replies come back to the chat. Zero dependencies.",
   "type": "module",
   "bin": {
-    "claude-telegram-bot": "bot.mjs"
+    "claude-telegram-bot": "bot.mjs",
+    "ctb": "ctb.mjs"
+  },
+  "exports": {
+    "./session.mjs": "./session.mjs"
   },
   "files": [
     "bot.mjs",
+    "ctb.mjs",
+    "session.mjs",
     "config.example.json",
     "com.claudebot.example.plist"
   ],

package/session.mjs

@@ -0,0 +1,129 @@
+// Standalone Claude session manager — zero-dependency (Node 18+ built-ins only).
+// Maintains conversational context across calls by persisting --resume session IDs.
+//
+// Usage:
+//   import { createSession } from 'claude-telegram-bot/session.mjs'
+//
+//   const session = createSession({ projectDir: '/my/project' })
+//   const r1 = await session.run('리팩토링 계획 세워줘')
+//   const r2 = await session.run('그걸 실제로 실행해줘')  // r1 컨텍스트 유지
+//   session.reset()                                       // 세션 초기화
+//
+// statePath defaults to <projectDir>/.claude-bot/session.json.
+// To share state with a running bot, pass the bot's state path explicitly:
+//   statePath: '/path/to/bot-config-dir/.claude-bot/state.json'
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { spawn } from 'node:child_process'
+
+function loadState(statePath) {
+  try {
+    return JSON.parse(readFileSync(statePath, 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+function saveState(statePath, state) {
+  try {
+    mkdirSync(dirname(statePath), { recursive: true })
+    writeFileSync(statePath, JSON.stringify(state, null, 2))
+  } catch (e) {
+    console.error('Failed to save session state:', e.message)
+  }
+}
+
+function _runClaude(prompt, sessionId, opts) {
+  return new Promise((resolve) => {
+    const {
+      projectDir = process.cwd(),
+      permissionMode = 'acceptEdits',
+      model,
+      claudeBin = 'claude',
+      appendSystemPrompt,
+      env = {},
+    } = opts
+
+    const args = [
+      '-p', prompt,
+      '--output-format', 'json',
+      '--permission-mode', permissionMode,
+    ]
+    if (model) args.push('--model', model)
+    if (appendSystemPrompt) args.push('--append-system-prompt', appendSystemPrompt)
+    if (sessionId) args.push('--resume', sessionId)
+
+    const child = spawn(claudeBin, args, {
+      cwd: projectDir,
+      env: { ...process.env, ...env },
+    })
+
+    let out = '', err = ''
+    child.stdout.on('data', (d) => { out += d })
+    child.stderr.on('data', (d) => { err += d })
+    child.on('error', (e) => resolve({ ok: false, text: `Failed to start claude: ${e.message}` }))
+    child.on('close', (code) => {
+      try {
+        const j = JSON.parse(out)
+        resolve({
+          ok: !j.is_error,
+          text: j.result ?? '(empty response)',
+          sessionId: j.session_id,
+          cost: j.total_cost_usd,
+        })
+      } catch {
+        resolve({
+          ok: false,
+          text: `Execution error (exit ${code}):\n${(err || out || 'no output').slice(0, 3500)}`,
+        })
+      }
+    })
+  })
+}
+
+/**
+ * Create a stateful Claude session.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.projectDir]        Working directory for claude (default: process.cwd())
+ * @param {string} [opts.statePath]         Where to persist the session ID (default: <projectDir>/.claude-bot/session.json; bot uses <configDir>/.claude-bot/state.json)
+ * @param {string} [opts.permissionMode]    Claude permission mode (default: 'acceptEdits')
+ * @param {string} [opts.model]             Model override (e.g. 'sonnet', 'opus')
+ * @param {string} [opts.claudeBin]         Path to the claude CLI (default: 'claude')
+ * @param {string} [opts.appendSystemPrompt] Extra system prompt to append
+ * @param {object} [opts.env]               Extra environment variables
+ * @returns {{ run(prompt: string): Promise<{ok, text, sessionId, cost}>, reset(): void, getSessionId(): string|undefined }}
+ */
+export function createSession(opts = {}) {
+  const projectDir = opts.projectDir ?? process.cwd()
+  const statePath = opts.statePath ?? join(projectDir, '.claude-bot', 'session.json')
+  const claudeOpts = {
+    projectDir,
+    permissionMode: opts.permissionMode ?? 'acceptEdits',
+    model: opts.model,
+    claudeBin: opts.claudeBin ?? 'claude',
+    appendSystemPrompt: opts.appendSystemPrompt,
+    env: opts.env ?? {},
+  }
+
+  let state = loadState(statePath)
+
+  return {
+    async run(prompt) {
+      const res = await _runClaude(prompt, state.sessionId, claudeOpts)
+      if (res.sessionId) {
+        state.sessionId = res.sessionId
+        saveState(statePath, state)
+      }
+      return res
+    },
+    reset() {
+      state.sessionId = undefined
+      saveState(statePath, state)
+    },
+    getSessionId() {
+      return state.sessionId
+    },
+  }
+}