claude-telegram-bot 0.1.0 → 0.2.1

package/README.ko.md

@@ -1,306 +1,255 @@
-# Claude Telegram Bot (범용)
+# Claude Telegram Bot
 
 **한국어** · [English](./README.md)
 
-**의존성 0, 단일 파일, 데몬으로 도는 Claude Code 봇 — Bun도 Python도 떠 있는 세션도 필요 없음.**
-
-텔레그램 메시지를 받아 지정한 프로젝트 폴더에서 `claude -p`(헤드리스 모드)를 실행하고
-결과를 다시 텔레그램으로 보내주는 작은 브릿지. `bot.mjs` 파일 하나, Node 18+ 내장 기능만 사용 —
-`npm install`할 것도 없고, 감사(audit)할 거라곤 읽기 쉬운 ~400줄이 전부.
+텔레그램으로 메시지를 보내면, 집이나 서버에 켜둔 Claude Code가 작업하고 결과를 다시 텔레그램으로 돌려주는 봇입니다.
 
 ```
-[너] → Telegram → bot.mjs → claude -p (config.projectDir) → 결과 → Telegram
+[나] → 텔레그램 → bot.mjs → claude -p (작업 폴더) → 결과 → 텔레그램
 ```
 
-검증 완료: `bypassPermissions` 헤드리스 모드 정상 동작 확인. 쉘·git·테스트까지 자동 실행됨.
-**백그라운드 데몬**(launchd)으로 돌아서 인터랙티브 세션을 열어둘 필요가 없음.
+## 왜 만들었나
 
-> ### ⚠️ 이 도구는 설계상 원격 코드 실행 도구입니다. 실행 전에 [보안](#-보안) 섹션을 꼭 읽으세요.
-> 텔레그램으로 보낸 메시지는 봇이 도는 머신에서 **명령으로 실행**됩니다.
-> `permissionMode: bypassPermissions`면 한 줄짜리 메시지가 네 계정 권한으로 **무엇이든** 실행할 수 있습니다.
+자리를 비운 사이에도 폰으로 빌드를 돌려보거나 간단한 수정을 맡기고 싶을 때가 있습니다. 그렇다고 외부에서 데스크톱에 원격 접속해서 터미널을 여는 건 번거롭죠.
 
-## 다른 도구와 비교
+텔레그램 봇이면 충분합니다. 메시지를 보내면 집(또는 개인 서버)의 `claude`가 헤드리스로 돌아 작업하고, 답을 채팅으로 보내줍니다. 별도 웹 대시보드도, 추가 서버도 없습니다. 파일 하나(`bot.mjs`)와 설정 파일 하나가 전부입니다.
 
-이 분야는 이미 붐비고, Anthropic도 공식 솔루션을 내놨다. 솔직한 지도를 그려두니 용도에 맞게 고르면 된다:
+## 이런 분께
 
-| | 이 봇 | [공식 Claude Code Channels](https://code.claude.com/docs/en/channels) | [claude-code-telegram](https://github.com/RichardAtCT/claude-code-telegram) |
-|---|---|---|---|
-| 런타임 | **Node 내장만** | Bun + MCP 플러그인 | Python 3.11+ + 라이브러리 |
-| 실행 모델 | 메시지당 헤드리스 `claude -p` | **열려있는** `claude --channels` 세션에 이벤트 push | Claude SDK / CLI |
-| 상시 가동 형태 | **백그라운드 데몬** (세션 안 떠도 됨) | 계속 떠 있는 인터랙티브 세션 | 서비스 / 데몬 |
-| 한 레포에 권한 차등 멀티 페르소나 | **가능** (개발자=`bypass`, 기획자=`plan`) | 불가 | 불가 |
-| 작업별 권한 승인 (인라인 버튼) | 없음 (`permissionMode`로) | **있음** | 일부 |
-| 기능 폭 (웹훅·cron·음성·export) | 최소 | 중간 | **큼** |
-| 읽고/포크할 코드량 | **~400줄, 단일 파일** | 큼 | 큼 |
+- 외출·이동 중에 폰으로 테스트나 빌드를 돌려보고 싶은 분
+- 자리를 비운 사이 간단한 수정·커밋을 맡겨두고 싶은 분
+- 맥미니나 홈서버에 띄워두고 어디서든 접속하고 싶은 분
+- 거창한 셀프호스트 구성 없이 텔레그램만으로 끝내고 싶은 분
 
-**작업별 승인이 필요하고** 세션을 열어두는 게 괜찮다면 → 공식 Channels. **기능이 많이 필요하면** →
-claude-code-telegram. **의존성 0·감사 가능·데몬**이 필요하거나, 특히 같은 프로젝트에 **권한이 다른
-역할별 페르소나 봇**을 띄우고 싶다면 → 이 봇.
+OpenClaw처럼 웹 UI까지 갖춘 구성을 써봤다면, 이 프로젝트는 그 반대편이라고 보면 됩니다. 대시보드도 데이터베이스도 없고, 이미 설치해 로그인해 둔 `claude` CLI를 그대로 불러 쓰는 게 전부입니다. 설정과 코드를 30초면 훑어볼 수 있습니다.
 
-## 여러 프로젝트 동시 운영
+## 동작 방식
 
-이 코드는 프로젝트 비종속이라, **프로젝트마다 config 파일 하나씩**만 만들면 여러 개를 동시에 돌릴 수 있다.
+- 텔레그램 봇 API를 롱폴링으로 받습니다.
+- 메시지가 오면 작업 폴더(`projectDir`)에서 `claude -p`(헤드리스 모드)를 실행합니다.
+- 세션은 `--resume`으로 이어지므로, 봇을 재시작해도 대화 맥락이 유지됩니다.
+- 의존성이 없습니다. Node 18+ 내장 기능(`fetch`, `child_process`)만 씁니다.
 
-- 실행: `node bot.mjs /절대경로/프로젝트.config.json` (인자 없으면 같은 폴더의 `config.json`)
-- 상태(`state.json`)·첨부(`attachments/`)는 **그 config 파일이 있는 폴더**에 저장돼 프로젝트끼리 안 섞임
-- **주의**: 텔레그램은 토큰당 폴링 1개만 허용 → 프로젝트마다 **BotFather 토큰을 따로** 만들어야 동시 운영 가능
-- 상시 가동은 `com.claudebot.example.plist`를 프로젝트별로 복사해 등록 (아래 launchd 섹션 참고)
+## 다른 도구와 비교
 
-예) 두 프로젝트:
-```
-~/projects/A/claudebot.config.json   (토큰 A, projectDir=~/projects/A)
-~/projects/B/claudebot.config.json   (토큰 B, projectDir=~/projects/B)
-node bot.mjs ~/projects/A/claudebot.config.json   # 인스턴스 A
-node bot.mjs ~/projects/B/claudebot.config.json   # 인스턴스 B
-```
+이 분야에는 이미 여러 도구가 있고, Anthropic도 공식 기능을 내놨습니다. 용도에 맞게 고르시면 됩니다.
 
-## 여러 페르소나(역할) 봇
+| | 이 봇 | [공식 Claude Code Channels](https://code.claude.com/docs/en/channels) | [claude-code-telegram](https://github.com/RichardAtCT/claude-code-telegram) |
+|---|---|---|---|
+| 런타임 | Node 내장만 | Bun + MCP 플러그인 | Python 3.11+ |
+| 실행 모델 | 메시지마다 `claude -p` | 떠 있는 세션에 이벤트 push | Claude SDK / CLI |
+| 상시 가동 | 백그라운드 데몬 | 인터랙티브 세션 유지 | 서비스 / 데몬 |
+| 권한 차등 페르소나 | 가능 | 불가 | 불가 |
+| 작업별 권한 승인 버튼 | 없음 | 있음 | 일부 |
+| 기능 범위 | 최소 | 중간 | 많음 |
 
-**같은 프로젝트**를 역할별 봇으로 나눠 띄울 수 있다 (예: **개발자** + **기획자**).
-코드는 하나, **config 파일만 역할별로** 따로 둔다.
+정리하면 이렇습니다.
 
-- **`persona`**: config에 역할 시스템 프롬프트를 넣으면 그 봇의 정체성이 된다.
-  텔레그램용 간결 지침은 자동으로 함께 주입되므로 `persona`엔 역할만 적으면 됨.
-- **`permissionMode`로 권한 차등**: 같은 폴더를 공유하므로 **셸을 쓰는 봇(`bypassPermissions`)은
-  하나로 제한**하면 동시 편집 충돌을 피할 수 있다. 읽기·계획만 시키려면 `plan`.
-- **세션 분리**: `state` 파일은 config 이름에서 파생된다
-  (`config.json`→`state.json`, `dev.config.json`→`dev.config.state.json`). 같은 폴더에
-  config 여러 개를 둬도 봇끼리 맥락이 안 섞임.
-- **봇마다 토큰 1개**: 각 봇은 BotFather에서 별도 토큰 발급 (`allowedChatId`는 동일해도 됨).
+- 작업마다 승인 버튼이 필요하고 세션을 계속 띄워둬도 괜찮다면 → **공식 Channels**
+- 웹훅, cron, 음성 등 기능이 많이 필요하다면 → **claude-code-telegram**
+- 구성을 최대한 단순하게 가져가고 싶거나, 한 코드로 여러 페르소나 봇을 굴리고 싶다면 → **이 봇**
 
-예) 개발자 + 기획자:
-```
-dev.config.json       (permissionMode: bypassPermissions, persona: "시니어 개발자...")
-planner.config.json   (permissionMode: plan,              persona: "기획자 겸 UX 담당...")
-node bot.mjs dev.config.json
-node bot.mjs planner.config.json
-```
+## 요구 사항
 
-| 봇 | permissionMode | 역할 |
-|---|---|---|
-| 개발자 | `bypassPermissions` | 코드 구현·수정·테스트·git |
-| 기획자 | `plan` (읽기·계획만) | 기능 제안·스펙·UX/디자인 방향 |
+- Node.js 18 이상 (내장 `fetch` 사용)
+- `claude` CLI 설치 및 로그인 (봇은 이 인증을 그대로 씁니다)
+- 텔레그램 봇 토큰 ([@BotFather](https://t.me/BotFather)에서 발급)
 
-> 상시 가동은 `com.claudebot.example.plist`를 **봇마다** 복사해 `Label`·config 인자·로그
-> 경로를 다르게 등록한다 (아래 launchd 섹션 참고).
+상시 가동 예시는 macOS의 launchd 기준입니다. 리눅스라면 systemd나 pm2로 같은 구성을 만들면 됩니다.
 
----
+## 설치 & 실행
 
-## ⚡ 빠른 시작 (내가 할 일)
+라이브러리가 아니라 단독으로 도는 CLI입니다. `import`해서 쓰는 게 아니라, 전역으로 설치하거나 `npx`로 실행합니다. 작업 폴더는 설정의 `projectDir`로 정하므로, 봇을 어디에 설치하든 상관없습니다.
 
-**1) 봇 토큰 발급** — 텔레그램에서 `@BotFather` → `/newbot` → 이름/username 지정 → 토큰 복사
+**npx로 바로 실행**
 
-**2) 설정 파일 생성**
 ```sh
-cd /Users/jtchoi/Projects/cube-brain-trainer/tools/claude-telegram-bot
-cp config.example.json config.json
-# config.json 에 BotFather 토큰만 붙여넣기 (allowedChatId 는 일단 비워둠)
-# permissionMode 는 이미 bypassPermissions 로 설정돼 있음
+npx claude-telegram-bot init        # 현재 폴더에 config.json 생성
+# config.json 편집 (token, projectDir 등)
+npx claude-telegram-bot             # config.json 으로 실행
 ```
 
-**3) chatId 알아내기 + 실행**
+**전역 설치 (상시 가동에 권장)**
+
 ```sh
-node bot.mjs
-# → 텔레그램에서 봇에게 아무 메시지나 전송 → 봇이 이 채팅의 chatId 를 답장
-# → 그 숫자를 config.json 의 allowedChatId 에 넣고 봇 재시작 (Ctrl+C 후 다시 node bot.mjs)
-# 이제 너만 사용 가능
+npm i -g claude-telegram-bot
+
+claude-telegram-bot init ~/botconfigs/myproj    # 해당 경로에 config.json 생성
+# config.json 편집
+claude-telegram-bot ~/botconfigs/myproj/config.json
 ```
 
-**4) 사용** — 텔레그램으로 메시지 전송:
-- `cross 솔버 테스트 돌리고 통과하면 커밋 후 push 해줘`
-- `solve-2nd-floor-edges.ts 에 엣지 케이스 추가해줘`
+> **설정 파일은 git에 올리지 마세요.** config 파일에는 봇 토큰이 들어 있습니다. git 레포 안에 둔다면 `config.json`, `state*.json`, `attachments/`를 그 프로젝트의 `.gitignore`에 추가하세요. 이 레포는 해당 패턴을 이미 무시하므로 `claudebot.config.json` 같은 이름도 안전하지만, 다른 프로젝트는 직접 지정해야 합니다.
 
-**5) 항상 켜두기** (선택)
-```sh
-cp com.cube.claudebot.plist ~/Library/LaunchAgents/
-launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.cube.claudebot.plist
-tail -f bot.log
-```
+## 설정
+
+`config.json`의 키는 다음과 같습니다.
 
-> ⚠️ 봇은 현재 작업 브랜치(`develop`) 기준으로 동작함. push 시점 등 브랜치 관리는 메시지로 명확히 지시할 것.
+| 키 | 설명 |
+|---|---|
+| `token` | BotFather에서 받은 봇 토큰 |
+| `allowedChatId` | 처음엔 비워두세요. 봇이 chatId를 알려줍니다 (아래 첫 실행 참고) |
+| `projectDir` | Claude가 작업할 폴더의 절대경로 |
+| `claudeBin` | `which claude` 결과 (절대경로 권장) |
+| `permissionMode` | `plan`(읽기·계획만) / `acceptEdits`(편집 자동 승인) / `bypassPermissions`(쉘 포함 전부 자동) |
+| `model` | 비우면 기본 모델. `opus`, `sonnet` 등 |
+| `lang` | (선택) UI 언어. 비우면 사용자별 자동 판별(기본 영어, 텔레그램이 한국어면 한국어). `"en"`/`"ko"`로 고정 가능 |
+| `name` | (선택) `/help`에 표시되는 봇 이름. 여러 봇 구분용 |
+| `persona` | (선택) 역할 시스템 프롬프트. 페르소나 봇 정의용 |
+| `appendSystemPrompt` | (선택) 기본 "간결하게 답하기" 지침을 직접 덮어쓸 때 |
+| `env` | (선택) `claude` 프로세스에 넘길 환경 변수 |
+| `schedule` | (선택) 정해진 시각에 프롬프트를 실행하는 cron 작업 — [예약 작업](#예약-작업-cron) 참고 |
 
-자세한 설명은 아래 섹션 참고.
+`state.json`과 첨부 파일(`attachments/`)은 config 파일과 같은 폴더에 저장됩니다. 그래서 config만 따로 두면 프로젝트끼리 섞이지 않습니다.
 
----
+## 첫 실행
 
-## 1. 봇 만들기 (BotFather)
+1. **봇 토큰 발급** — 텔레그램에서 [@BotFather](https://t.me/BotFather)에게 `/newbot`을 보내고, 이름과 username(`_bot`으로 끝나야 함)을 정하면 토큰을 줍니다. `config.json`의 `token`에 넣고 `allowedChatId`는 비워둡니다.
+2. **chatId 확인 후 잠그기** — 봇을 실행하고 텔레그램에서 아무 메시지나 보내면, 봇이 이 채팅의 `chatId`를 답장합니다. 그 숫자를 `allowedChatId`에 넣고 재시작하면 나만 쓸 수 있습니다. ([보안](#보안) 참고 — 이게 유일한 인증 수단입니다.)
+3. **사용** — 그냥 메시지를 보냅니다.
+   - `테스트 돌려보고 통과하면 커밋하고 push 해줘`
+   - `api.ts 에 에러 핸들링 추가해줘`
 
-1. 텔레그램에서 **@BotFather** 검색 → 대화 시작
-2. `/newbot` 입력 → 봇 이름과 username 지정 (username은 `_bot`으로 끝나야 함)
-3. 받은 **토큰**을 복사 (예: `123456789:AAxxxxxxxx`)
+명령어: `/new`(맥락 초기화) · `/cron`(예약 작업 보기·추가·삭제) · `/restart`(문법 검사 후 재시작) · `/id`(채팅 ID 확인) · `/help`(도움말)
 
-## 2. 설정
+> **`/restart`** 는 먼저 `bot.mjs` 에 `node --check` 를 돌려 **문법 오류가 있으면 재시작을 취소**합니다(잘못된 수정이 봇을 크래시 루프에 빠뜨리는 것 방지). 통과하면 프로세스를 종료하고, 다시 띄우는 건 프로세스 관리자에게 맡깁니다. [launchd 설정](#상시-실행-launchd)(`KeepAlive`)이면 바로 동작하고, 관리자 없이 `node bot.mjs` 로만 돌리면 그냥 멈춥니다. 재시작 후 대화 세션은 `state.json` 의 ID로 이어집니다.
 
-```sh
-cd tools/claude-telegram-bot
-cp config.example.json config.json
-```
+## 사용 메모
 
-`config.json` 편집:
+- **세션 유지** — 대화는 `--resume`으로 자동으로 이어집니다. 마지막 세션 ID가 `state.json`에 저장되므로 봇을 재시작해도 맥락이 남습니다. 새로 시작하려면 `/new`.
+- **간결한 답변** — 텔레그램에 맞게 짧게 답하도록 시스템 프롬프트가 기본으로 붙습니다. 바꾸려면 `appendSystemPrompt`에 직접 넣으세요 (빈 문자열이면 끔).
+- **언어** — 봇 자체 문구(`/help`, 명령 메뉴, 상태 메시지)는 **기본 영어**, 텔레그램이 한국어인 사용자에겐 한국어로 나옵니다. `lang`(`"en"`/`"ko"`)으로 고정할 수 있습니다. Claude의 실제 답변은 **사용자가 쓴 언어**를 따라갑니다. `/` 명령 메뉴는 `setMyCommands`로 언어별 등록됩니다.
+- **서식 변환** — 답변의 마크다운(굵게·코드·표 등)을 텔레그램 HTML로 바꿔 보냅니다. 변환이 깨지는 경우엔 평문으로 다시 보냅니다.
+- **첨부 파일** — 사진·문서·음성·영상을 보내면 `attachments/`에 내려받고, 그 경로를 Claude에게 전달합니다(캡션도 함께). 이미지는 Read로 열어볼 수 있습니다.
 
-| 키 | 설명 |
-|---|---|
-| `token` | BotFather에서 받은 토큰 |
-| `allowedChatId` | **비워두고 시작** → 봇이 알려줌 (아래 3단계) |
-| `projectDir` | 작업 폴더 (기본값 그대로 두면 됨) |
-| `claudeBin` | `which claude` 결과 (절대경로 권장) |
-| `permissionMode` | `plan`(읽기·계획만) / `acceptEdits`(파일편집 자동승인) / `bypassPermissions`(전부 자동, 쉘 포함) |
-| `model` | 비워두면 기본 모델. `opus` / `sonnet` 등 |
-| `name` | (선택) `/help`에 표시되는 봇 이름 — 멀티 봇 구분용 |
-| `persona` | (선택) 역할 시스템 프롬프트 — 페르소나(개발자/기획자 등) 정의. 자세히는 아래 페르소나 섹션 |
+## 예약 작업 (cron)
 
-## 3. 내 chatId 알아내기
+config에 `schedule` 배열을 두면 정해진 시각에 프롬프트를 자동 실행합니다 — 아침 브리핑, 주기적 점검, 리마인더 등. 각 항목은 프롬프트를 실행하고 결과를 `allowedChatId`로 보냅니다.
 
-```sh
-node bot.mjs
+```json
+"schedule": [
+  { "cron": "0 9 * * 1-5", "label": "아침 브리핑", "prompt": "오늘 처리할 이슈/할 일을 요약해줘" },
+  { "cron": "*/30 * * * *", "prompt": "CI 상태 확인해서 빨간 게 있을 때만 알려줘" }
+]
 ```
 
-실행 후 텔레그램에서 봇에게 아무 메시지나 보내면, 봇이 **이 채팅의 chatId**를 답장해줌.
-그 숫자를 `config.json`의 `allowedChatId`에 넣고 봇을 재시작. → 이제 너만 쓸 수 있음.
-
-## 4. 사용
+- **`cron`** — 표준 5필드 `분 시 일 월 요일` (예: `0 9 * * 1-5` = 평일 09:00). `*`, 목록(`1,3,5`), 범위(`1-5`), 스텝(`*/15`)을 지원합니다. 요일 `0`과 `7`은 둘 다 일요일. 시각은 **호스트의 로컬 시간대** 기준입니다. 외부 의존성 없이 파서가 `bot.mjs` 안에 들어 있습니다.
+- **`prompt`**(필수) — Claude에게 보낼 메시지. **`label`**(선택) — 답장 푸터와 `/cron` 목록에 표시되는 짧은 이름.
+- **새 세션** — 예약 작업은 **독립된 세션**으로 돌아가서 내 대화 맥락을 오염시키지 않습니다(`state.json`은 내 것 그대로). 단일 작업 락을 공유하므로, 발사 시점에 다른 작업이 진행 중이면 그 회차는 **건너뜁니다**(로그 남김).
 
-봇에게 그냥 메시지를 보내면 됨:
+**채팅에서 자연어로 추가하기**
 
-- `cross 솔버 테스트 돌려보고 결과 알려줘`
-- `solve-2nd-floor-edges.ts 에 엣지 케이스 추가해줘`
+```
+/cron add 매일 아침 9시에 열린 이슈 요약해줘
+```
 
-명령어:
-- `/new` — 대화 맥락 초기화 (새 세션)
-- `/id` — 채팅 ID 확인
-- `/help` — 도움말
+봇이 이 문장을 Claude에게 보내 cron 표현식으로 바꾸고, **해석한 내용을 되돌려 보여줍니다**(잘못 읽었으면 바로 확인 가능). 그리고 `state.json`에 저장하므로 **재시작이 필요 없습니다**. 동적 작업에는 번호가 붙고, 다음으로 관리합니다.
 
-세션은 자동으로 이어짐 (`--resume`). `state.json`에 마지막 세션 ID가 저장돼서
-봇을 재시작해도 맥락이 유지됨. 맥락을 끊고 싶으면 `/new`.
+- `/cron` — 전체 목록 (config 작업은 `[config]`, 동적 작업은 `#번호`로 표시)
+- `/cron add <자연어 요청>` — 예: `/cron add 30분마다 CI 빨간 거 있으면 알려줘`
+- `/cron rm <번호>` — 동적 작업 삭제 (config 작업은 파일에서 수정)
 
-### 응답 형식 / 첨부
+config에 적은 작업은 바꾸려면 재시작이 필요하고, 채팅으로 추가한 작업만 즉시 반영됩니다.
 
-- **간결 모드**: 텔레그램용으로 짧게 답하도록 `--append-system-prompt`가 기본 적용됨.
-  지침을 바꾸려면 `config.json`의 `appendSystemPrompt`에 문자열을 넣으면 됨(빈 문자열이면 비활성).
-- **서식**: 응답의 마크다운(굵게/코드/제목/표)을 텔레그램 HTML로 변환해 전송함.
-  변환이 실패하는 예외 케이스는 자동으로 평문으로 재전송됨.
-- **파일 첨부**: 사진/문서/음성/영상을 보내면 `attachments/`에 내려받아 그 경로를
-  Claude에게 전달함(캡션은 메시지로 같이 전달). 이미지도 Read로 열어볼 수 있음.
+## 여러 프로젝트 / 페르소나
 
----
+코드는 프로젝트에 종속되지 않습니다. config 파일만 하나씩 더 만들면 여러 봇을 동시에 굴릴 수 있습니다.
 
-## 5. 실행 방법
+```sh
+claude-telegram-bot ~/projects/A/claudebot.config.json   # 프로젝트 A
+claude-telegram-bot ~/projects/B/claudebot.config.json   # 프로젝트 B
+```
 
-| 방법 | 터미널 닫으면 | 재부팅 후 | 크래시 시 | 용도 |
-|---|---|---|---|---|
-| `node bot.mjs` | 종료됨 | ✗ | ✗ | 테스트·chatId 확인 |
-| `nohup node bot.mjs > bot.log 2>&1 &` | 유지 | ✗ | ✗ | 임시 백그라운드 |
-| **launchd (LaunchAgent)** | 유지 | ✅ 자동 시작 | ✅ 자동 재시작 | **상시 가동 (권장)** |
+- 텔레그램은 토큰 하나당 폴링 하나만 허용합니다. 그래서 봇마다 BotFather 토큰을 따로 발급해야 합니다.
+- `state`와 `attachments`는 config 옆에 저장되므로 봇끼리 섞이지 않습니다.
 
-> `node bot.mjs &` 도 백그라운드로 돌긴 하지만 터미널을 닫으면 SIGHUP으로 같이 죽음.
-> 터미널을 닫아도 유지하려면 최소 `nohup`, 재부팅·크래시까지 견디려면 launchd.
+**같은 프로젝트**를 역할별 봇으로 나눌 수도 있습니다. 예를 들어 개발자 봇과 기획자 봇으로요. 코드는 그대로 두고 config만 역할별로 둡니다.
 
----
+| 봇 | permissionMode | 역할 |
+|---|---|---|
+| 개발자 | `bypassPermissions` | 구현·수정·테스트·git |
+| 기획자 | `plan` | 기능 제안·스펙·UX 방향 |
 
-## 6. 항상 켜두기 (launchd 설정)
+- `persona`에 역할 프롬프트를 넣으면 그 봇의 정체성이 됩니다. (텔레그램용 간결 지침은 자동으로 같이 붙습니다.)
+- 같은 폴더를 공유한다면 쉘을 쓰는 봇(`bypassPermissions`)은 하나로 제한하는 편이 안전합니다. 동시 편집 충돌을 피할 수 있습니다.
+- `state` 파일 이름은 config 이름에서 만들어집니다 (`dev.config.json` → `dev.config.state.json`). 같은 폴더에 config가 여러 개여도 맥락이 안 섞입니다.
 
-맥 재부팅·크래시에도 자동으로 살아나는 상시 가동 방식. 로그인 세션에서 도는
-**LaunchAgent**라서 claude의 키체인/OAuth 인증을 그대로 사용함.
+## 상시 실행 (launchd)
 
-### 6-1. plist 확인 (경로/노드 버전 점검)
+맥을 재부팅하거나 봇이 죽어도 자동으로 다시 뜨게 하려면 launchd를 씁니다. 로그인 세션에서 도는 LaunchAgent라서 `claude`의 키체인/OAuth 인증을 그대로 사용합니다.
 
-`com.cube.claudebot.plist`는 아래 경로들을 가정함. 다르면 먼저 수정:
+저장소의 `com.claudebot.example.plist`를 복사해 쓰면 됩니다. 먼저 경로부터 확인하세요.
 
 ```sh
-which node     # ProgramArguments 첫 줄의 node 경로와 일치하는지
-which claude   # PATH 에 이 디렉토리가 포함됐는지 (EnvironmentVariables)
+which node     # ProgramArguments 첫 줄의 node 경로와 같은지
+which claude   # 이 경로가 PATH(EnvironmentVariables)에 포함됐는지
 ```
 
-plist에서 확인할 항목:
-- `ProgramArguments` 1번째 — node 절대경로
-- `ProgramArguments` 2번째 — `bot.mjs` 절대경로
-- `WorkingDirectory` — 프로젝트 폴더
-- `EnvironmentVariables > PATH` — nvm node/claude 경로 포함
+plist에서 맞춰야 할 항목:
+
+- `ProgramArguments` — node 절대경로, `bot.mjs` 절대경로, config 절대경로
+- `WorkingDirectory` — 작업 폴더
+- `EnvironmentVariables > PATH` — node·claude 경로 포함
 - `StandardOutPath` / `StandardErrorPath` — 로그 파일 경로
+- `Label` — 봇마다 고유하게 (예: `com.claudebot.myproj`)
 
-### 6-2. 등록 & 시작
+등록과 관리:
 
 ```sh
-cd /Users/jtchoi/Projects/cube-brain-trainer/tools/claude-telegram-bot
-cp com.cube.claudebot.plist ~/Library/LaunchAgents/
-launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.cube.claudebot.plist
-```
-
-> 최신 macOS 권장 방식은 `bootstrap`/`bootout`. 구버전(`load`/`unload`)도 동작하지만
-> deprecated 경고가 뜰 수 있음. `bootstrap`이 안 되면 `launchctl load ~/Library/LaunchAgents/com.cube.claudebot.plist`로 대체.
+cp com.claudebot.example.plist ~/Library/LaunchAgents/
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claudebot.example.plist
 
-### 6-3. 상태 확인 & 관리
-
-```sh
-launchctl list | grep claudebot      # 등록·동작 확인 (PID가 보이면 실행 중)
-tail -f bot.log                      # 실행 로그
-tail -f bot.error.log                # 에러 로그
+launchctl list | grep claudebot      # 상태 확인 (PID가 보이면 실행 중)
+tail -f bot.log                      # 로그
 
 # 중지
-launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.cube.claudebot.plist
+launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.claudebot.example.plist
 
-# 코드 수정 후 재시작 (bootout → bootstrap)
-launchctl bootout   gui/$(id -u) ~/Library/LaunchAgents/com.cube.claudebot.plist
-launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.cube.claudebot.plist
+# 코드 수정 후 재시작
+launchctl bootout   gui/$(id -u) ~/Library/LaunchAgents/com.claudebot.example.plist
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claudebot.example.plist
 ```
 
-### 6-4. 자주 겪는 문제
-
-- **`launchctl list`에 PID 없이 에러 코드만 보임** → `bot.error.log` 확인. 보통 node/claude
-  경로 문제(`command not found`)거나 `config.json` 누락.
-- **봇이 응답 없음** → claude 인증 만료일 수 있음. 터미널에서 `node bot.mjs` 직접 실행해
-  `claude` 로그인 상태부터 확인.
-- **맥이 잠자기 모드면 폴링도 멈춤** → 시스템 설정 > 배터리/전원에서 절전 해제 권장.
-- **"폴링 오류" 반복 (ETIMEDOUT)** → 일부 네트워크에서 IPv6 경로가 막혀 Node의 fetch가
-  api.telegram.org(IPv6 보유)에서 타임아웃나는 문제. `bot.mjs`가 IPv4 우선
-  (`dns.setDefaultResultOrder('ipv4first')` + 자동선택 끄기)으로 이미 회피하도록 돼 있음.
-  그래도 안 되면 `curl https://api.telegram.org` 로 네트워크/방화벽부터 확인.
+> 최신 macOS는 `bootstrap`/`bootout`을 권장합니다. 구버전 `load`/`unload`도 동작하지만 deprecated 경고가 뜰 수 있습니다.
 
----
+## 자주 겪는 문제
 
-## ⚠️ 보안
+- **`launchctl list`에 PID 없이 에러 코드만 보임** — `bot.error.log`를 확인하세요. 보통 node/claude 경로 문제이거나 config 누락입니다.
+- **봇이 응답하지 않음** — `claude` 인증이 만료됐을 수 있습니다. 터미널에서 `node bot.mjs`를 직접 실행해 로그인 상태부터 확인하세요.
+- **맥이 잠자기에 들어가면 폴링도 멈춤** — 시스템 설정 > 배터리/전원에서 절전을 풀어두세요.
+- **폴링 오류 반복 (ETIMEDOUT)** — 일부 네트워크는 IPv6 경로가 막혀 있어 `fetch`가 타임아웃 납니다. `bot.mjs`는 IPv4를 우선하도록 이미 처리해 뒀습니다. 그래도 안 되면 `curl https://api.telegram.org`로 네트워크부터 확인하세요.
 
-**이 도구는 채팅 앱 안에 들어있는 SSH 키라고 생각하라.** 명령을 실행하는 게 목적이고,
-그 힘이 곧 위험이다. 노출 전에 반드시 읽을 것.
+## 보안
 
-### 위협 모델 — 누가 네 머신에서 명령을 실행할 수 있나
+이 봇은 **채팅으로 받은 메시지를 머신에서 명령으로 실행합니다.** 편한 만큼 위험하니 아래는 꼭 지키세요.
 
-1. **허가된 채팅.** `allowedChatId`로 허용한 텔레그램 계정에 접근 가능한 사람은 명령을 실행할 수 있다.
-   폰 잠금과 텔레그램 계정 2단계 인증(2FA)을 켜둘 것.
-2. **봇 토큰을 가진 사람.** 토큰은 봇의 비밀번호다. 토큰만 있으면 들어오는 메시지를 읽고 봇을 사칭할 수
-   있다. `allowedChatId` 화이트리스트가 명령 *실행*은 여전히 막아주지만(텔레그램이 부여하는 `chatId`는
-   위조 불가), **토큰 유출은 사고로 취급**하라. `@BotFather` → `/revoke`로 폐기하고 새로 발급할 것.
-3. **프롬프트 인젝션.** 웹페이지·파일·이슈 내용을 봇에 넘기며 처리시키면, 그 안에 숨은 악성 지시가
-   Claude를 조종할 수 있다. 신뢰할 수 없는 콘텐츠를 `bypassPermissions` 봇에 그대로 흘려넣지 말 것.
+**누가 명령을 실행할 수 있나**
 
-### 타협 불가 원칙
+- **허가된 채팅** — `allowedChatId`로 허용한 텔레그램 계정에 접근할 수 있는 사람. 폰 잠금과 텔레그램 2FA를 켜두세요.
+- **봇 토큰을 가진 사람** — 토큰은 봇의 비밀번호입니다. 토큰만으로 메시지를 읽고 봇을 사칭할 수 있습니다. `allowedChatId`가 명령 실행은 막아주지만(텔레그램이 주는 chatId는 위조 불가), 토큰이 새면 사고로 보고 `@BotFather`의 `/revoke`로 폐기하세요.
+- **프롬프트 인젝션** — 외부 웹페이지나 파일을 봇에 넘겨 처리시키면, 그 안에 숨은 지시가 Claude를 조종할 수 있습니다. 신뢰할 수 없는 내용을 `bypassPermissions` 봇에 그대로 넣지 마세요.
 
-- **`allowedChatId`는 반드시 설정.** 설정 전에는 봇이 아무 것도 실행하지 않고 채팅 ID만 알려준다.
-  설정 후에는 그 채팅만 명령 가능 — 이게 유일한 인증 계층이므로 반드시 채워야 한다.
-- **토큰을 자격증명처럼 보호.** `config.json`·`state.json`은 `.gitignore`에 있어 커밋되지 않는다 —
-  그대로 둘 것. 토큰을 이슈·로그·스크린샷에 절대 붙여넣지 말 것. 시작 로그는 토큰을 가린다
-  (`token: <redacted>`) — 되살리지 말 것.
-- **샌드박스는 없다.** 봇은 `claude`를 *네* 계정 권한으로 실행한다. 네 파일시스템, SSH/git 자격증명,
-  Claude OAuth/키체인 세션에 그대로 접근한다. 네가 할 수 있는 건 봇도 할 수 있다.
+**꼭 지킬 것**
 
-### 감당 가능한 최소 권한을 선택하라
+- `allowedChatId`를 반드시 설정하세요. 설정 전에는 봇이 아무것도 실행하지 않고 chatId만 알려줍니다. 이게 유일한 인증 수단입니다.
+- 토큰을 자격증명처럼 다루세요. 이슈·로그·스크린샷에 붙여넣지 마세요. 시작 로그는 토큰을 `<redacted>`로 가립니다.
+- 샌드박스는 없습니다. 봇은 `claude`를 내 계정 권한으로 실행합니다. 내 파일, SSH/git 자격증명, Claude 인증 세션에 그대로 접근합니다.
 
-`permissionMode`가 핵심 안전 다이얼이다:
+**권한 모드 선택**
 
 | 모드 | 허용 범위 | 권장 상황 |
 |---|---|---|
-| `plan` | 읽기·계획만, 편집 없음 | Q&A, 코드 리뷰, "기획자" 페르소나 |
-| `acceptEdits` | 파일 편집 자동 승인, 그 외(쉘 등)는 제한 | **권장 기본값** — 유용하면서 범위 제한 |
-| `bypassPermissions` | **임의 쉘 포함** 전부 자동 실행 | 채팅 한 줄 = 임의 코드 실행을 감수할 때 |
+| `plan` | 읽기·계획만 | Q&A, 코드 리뷰, 기획자 페르소나 |
+| `acceptEdits` | 파일 편집 자동, 쉘 등은 제한 | 기본값으로 무난 |
+| `bypassPermissions` | 쉘 포함 전부 자동 | 채팅 한 줄이 임의 코드 실행임을 감수할 때 |
 
-실전 강화 팁:
+- 자율 쉘·git이 꼭 필요한 게 아니면 `acceptEdits`를 쓰세요.
+- `projectDir`는 홈 디렉터리가 아니라 특정 프로젝트를 가리키게 해 피해 범위를 줄이세요.
+- 페르소나 봇을 여럿 둘 땐 하나만 `bypassPermissions`로 두고 나머지는 `plan`으로.
+- 상시 가동한다면 전용 계정이나 VM도 고려해 보세요.
 
-- 자율 쉘/git이 꼭 필요한 게 아니면 `bypassPermissions`보다 `acceptEdits`를 쓸 것.
-- `projectDir`는 홈 디렉터리가 아니라 **특정 프로젝트**를 가리키게 해 피해 범위를 줄일 것.
-- 멀티 페르소나에서는 **하나의** 봇만 `bypassPermissions`로 두고 나머지는 `plan`으로.
-- 상시 가동할 거면 전용 사용자 계정이나 VM에서 돌리는 것도 고려.
+보안 이슈는 공개로 올리기보다 GitHub 이슈(민감한 내용은 메인테이너에게 비공개)로 알려주세요.
 
-### 취약점 신고
+## 라이선스
 
-보안 이슈를 발견하면 익스플로잇 세부를 공개로 올리기보다 GitHub 이슈(민감한 건 메인테이너에게 비공개
-연락)로 알려주세요.
+MIT © Jongtaek Choi

package/README.md

@@ -103,43 +103,69 @@ sensitive reports) rather than posting exploit details publicly.
 
 ---
 
-## Quick start
+## Install & run
 
-**1) Create a bot token** — In Telegram, open `@BotFather` → `/newbot` → pick a name and a
-`username` ending in `_bot` → copy the token (looks like `123456789:AA...`).
+This is a standalone CLI/daemon, **not a library** — you don't `import` it. Install it globally (or
+run via `npx`), point a config file at any project, and run it. `projectDir` in the config decides
+which folder Claude works in, independent of where the bot is installed.
+
+Prerequisites: **Node 18+** and the **`claude` CLI installed and authenticated** on the host.
 
-**2) Create a config file**
+**Option A — npx (no install)**
 
 ```sh
-# from the repo folder
-cp config.example.json config.json
-# paste your BotFather token into config.json (leave allowedChatId empty for now)
+npx claude-telegram-bot init        # writes ./config.json
+# edit config.json (token, projectDir, …)
+npx claude-telegram-bot             # runs ./config.json
 ```
 
-Or scaffold one anywhere with the CLI:
+**Option B — global install (recommended for an always-on daemon)**
 
 ```sh
-node bot.mjs init ~/my-project    # writes ~/my-project/config.json
+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
 ```
 
-**3) Find your chatId and lock the bot to it**
+Run several projects/personas by making one config file each and passing its path —
+`state.json` and `attachments/` live next to that config, so they don't mix.
 
-```sh
-node bot.mjs
-# → send the bot any message in Telegram
-# → it replies with this chat's chatId
-# → put that number into config.json `allowedChatId`, then restart the bot (Ctrl+C, run again)
-# now only you can use it
-```
+> **Keep your config out of git.** The config file holds your bot token. If you drop one inside a git
+> repo, add it (plus `state*.json` and `attachments/`) to *that* project's `.gitignore`. This repo
+> already ignores `config.json`, `config.*.json`, `*.config.json`, `state*.json`, and `attachments/`,
+> so any name like `claudebot.config.json` is covered here — but your own project won't ignore them
+> until you say so.
 
-**4) Use it** — just send messages:
+### First-run steps
+
+**1) Create a bot token** — In Telegram, open `@BotFather` → `/newbot` → pick a name and a
+`username` ending in `_bot` → copy the token (looks like `123456789:AA...`). Put it in `config.json`,
+leave `allowedChatId` empty for now.
+
+**2) Find your chatId and lock the bot to it** — Start the bot (`claude-telegram-bot …`), send it any
+message in Telegram; it replies with this chat's `chatId`. Put that number into `config.json`
+`allowedChatId` and restart. Now only you can use it. (See [Security](#security) — this is your only
+auth layer.)
+
+**3) Use it** — just send messages:
 
 - `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) · `/id` (show chat ID) · `/help`.
+Commands: `/new` (reset context / new session) · `/cron` (list / add / remove scheduled tasks) · `/restart` (syntax-check & restart the bot) · `/id` (show chat ID) · `/help`.
+
+> **`/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
+> to relaunch it. Works out of the box with the [launchd setup](#always-on-with-launchd-macos)
+> (`KeepAlive`); under a bare `node bot.mjs` with no supervisor it just stops. Your session resumes
+> after the restart (the id lives in `state.json`).
+
+**4) Keep it always on (optional)** — see [Always-on with launchd](#always-on-with-launchd-macos).
 
-**5) Keep it always on (optional)** — see [Always-on with launchd](#always-on-with-launchd-macos).
+> **From source** (for hacking on the bot): clone the repo, `cp config.example.json config.json`,
+> then `node bot.mjs [config.json]`. Same behavior as the CLI.
 
 ---
 
@@ -159,10 +185,12 @@ Edit `config.json`:
 | `claudeBin` | Output of `which claude` (absolute path recommended) |
 | `permissionMode` | `plan` / `acceptEdits` / `bypassPermissions` — see [Security](#security) |
 | `model` | Empty = default. Or `opus` / `sonnet`, etc. |
+| `lang` | (optional) UI language. Empty = auto-detect per user (English default, Korean for Korean Telegram clients). Force with `"en"` / `"ko"`. |
 | `name` | (optional) Bot name shown in `/help` — handy for telling multiple bots apart |
 | `persona` | (optional) Role system prompt — defines a persona (developer/planner/…). See below |
 | `appendSystemPrompt` | (optional) Override the default "be concise for Telegram" instruction |
 | `env` | (optional) Extra environment variables passed to the `claude` process |
+| `schedule` | (optional) Cron jobs that run a prompt on a timer — see [Scheduled tasks](#scheduled-tasks-cron) |
 
 State (`state.json`) and downloaded `attachments/` are written **next to the config file**, so
 projects stay isolated.
@@ -171,6 +199,10 @@ projects stay isolated.
 
 - **Concise mode**: a `--append-system-prompt` is applied by default so replies stay short for
   Telegram. Override it via `appendSystemPrompt` (empty string disables it).
+- **Language**: the bot's own messages (`/help`, command menu, status text) are English by default
+  and switch to Korean for users whose Telegram client is Korean. Force one language with `lang`
+  (`"en"`/`"ko"`). Claude's actual replies follow the language you write in, regardless. The `/`
+  command menu is registered per-language via `setMyCommands`.
 - **Formatting**: the reply's Markdown (bold/code/headings/tables) is converted to Telegram-safe
   HTML. If conversion ever produces invalid HTML, the message is automatically resent as plain text.
 - **Attachments**: send a photo/document/voice/video and it's downloaded into `attachments/`; the
@@ -178,6 +210,44 @@ projects stay isolated.
 - **Sessions**: conversations resume automatically (`--resume`); the last session id is saved in
   `state.json`, so context survives restarts. Use `/new` to start fresh.
 
+### Scheduled tasks (cron)
+
+Add a `schedule` array to the config to run prompts on a timer — daily briefings, periodic
+checks, reminders. Each entry runs the prompt and sends the result to `allowedChatId`.
+
+```json
+"schedule": [
+  { "cron": "0 9 * * 1-5", "label": "Morning brief", "prompt": "Summarize today's open issues and TODOs" },
+  { "cron": "*/30 * * * *", "prompt": "Check CI status; only reply if something is red" }
+]
+```
+
+- **`cron`** — standard 5-field expression `minute hour day-of-month month day-of-week`
+  (e.g. `0 9 * * 1-5` = 09:00 on weekdays). Supports `*`, lists (`1,3,5`), ranges (`1-5`),
+  and steps (`*/15`). Day-of-week `0` and `7` both mean Sunday. Times use the **host's local
+  timezone**. No external dependency — the parser lives in `bot.mjs`.
+- **`prompt`** (required) — the message sent to Claude. **`label`** (optional) — a short name
+  shown in the reply footer and in `/cron`.
+- **Fresh session**: scheduled jobs run in their **own session** so they never pollute your
+  interactive conversation context (`state.json` stays yours). They share the single-task lock,
+  so a job is **skipped** (logged) if a task is already running when it fires.
+
+**Add jobs from the chat — in plain language:**
+
+```
+/cron add summarize open issues every weekday at 9am
+```
+
+The bot asks Claude to turn that into a cron expression, **echoes back what it understood**
+(so you can catch a misread), and saves it to `state.json` — **no restart needed**. Dynamic
+jobs get an id; manage them with:
+
+- `/cron` — list everything (config jobs are tagged `[config]`; dynamic ones show `#id`)
+- `/cron add <plain-language request>` — e.g. `/cron add every 30 min, ping me if CI is red`
+- `/cron rm <id>` — remove a dynamic job (config jobs are edited in the file)
+
+Config-defined jobs still require a restart to change; only chat-added jobs are live.
+
 ---
 
 ## Running multiple projects

package/config.example.json

@@ -1,12 +1,16 @@
 {
-  "name": "봇 이름 (도움말/구분용, 선택)",
-  "token": "BOTFATHER_에서_받은_봇_토큰",
+  "name": "Bot name (shown in /help, for telling bots apart; optional)",
+  "token": "BOT_TOKEN_FROM_BOTFATHER",
   "allowedChatId": "",
   "projectDir": "/ABSOLUTE/PATH/TO/PROJECT",
-  "claudeBin": "/Users/jtchoi/.nvm/versions/node/v23.1.0/bin/claude",
+  "claudeBin": "/ABSOLUTE/PATH/TO/claude",
   "permissionMode": "bypassPermissions",
   "model": "",
-  "persona": "이 봇의 역할/말투를 정의하는 시스템 프롬프트 (선택). 멀티 봇(개발자/기획자 등)에서 페르소나 구분에 사용.",
+  "lang": "",
+  "persona": "System prompt defining this bot's role/voice (optional). Used to differentiate persona bots (developer/planner/...).",
   "appendSystemPrompt": "",
-  "env": {}
+  "env": {},
+  "schedule": [
+    { "cron": "0 9 * * 1-5", "label": "Morning brief", "prompt": "Summarize today's open issues and TODOs (optional; standard 5-field cron: min hour day month weekday)" }
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-telegram-bot",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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": {