cloveric/tarocub

English | 中文文档 | Full Reference

Codex, Claude Code, 그리고 Antigravity를 로컬에서 실행하세요. Telegram 및 Feishu/Lark를 통해 이들을 제어할 수 있습니다.

TaroCub은 사용자의 머신에서 실제 CLI 에이전트 (CLI agents)를 실행한 다음, 이들에게 지속 가능한 채팅 인터페이스 (chat surfaces), 파일, 세션, 작업, cron, 감사 로그 (audit logs) 및 멀티 에이전트 워크플로우 (multi-agent workflows)를 제공합니다.

책상에 있든, 출퇴근 중이든, 반려견과 산책 중이든 상관없이 휴대폰에서 언제든지 로컬 세션을 재개할 수 있습니다.

Quick Start | Surfaces | Core Highlights | Lark Setup | Commands | Docs

TaroCub

은 호스팅된 에이전트 제품이 아닌 로컬 브리지 (local bridge)입니다. 사용자의 컴퓨터에서 실제 Codex, Claude Code, 그리고 Antigravity CLI를 실행한 다음, Telegram 및 Feishu/Lark를 통해 지속 가능한 메시징 제어 인터페이스를 제공합니다.

이 프로젝트의 이전 명칭은 cc-telegram-bridge였습니다.

공식 저장소는 이제 cloveric/tarocub입니다. GitHub에서 이전 URL로 리다이렉트하며, 호환성을 위해 기존 상태 디렉토리와 cctb 약어는 그대로 지원됩니다.

이 프로젝트는 이미 CLI 에이전트를 활발하게 사용하며 다음과 같은 기능을 원하는 사람들을 위해 구축되었습니다:

• Telegram 및 Feishu/Lark를 통한 모바일 우선 (phone-first) 운영;
• 카드, Docs 댓글, Sheets 및 그룹 워크플로우를 포함한 Feishu/Lark 네이티브 운영;
• 세션, cron 작업, 파일 전달, 사용량, 타임라인, 감사 로그 (audit logs) 및 멀티 에이전트 라우팅 (multi-agent routing)을 위한 지속 가능한 상태 (durable state).

의도된 설정 흐름은 에이전트 지원 방식입니다: 저장소를 클론(clone)하고, 이를 Codex, Claude Code 또는 Antigravity에서 연 다음, 에이전트에게 브리지를 대신 설정해 달라고 요청하세요. CLI가 존재하는 이유는 사용자가 모든 파일을 직접 수정하는 대신 로컬 에이전트가 지루한 설정 작업을 대신 수행할 수 있도록 하기 위함입니다.

이전의 긴 README는 Full Reference로 보존되어 있습니다. 이 랜딩 페이지는 의도적으로 짧게 작성되었습니다.

이 저장소를 Codex, Claude Code 또는 Antigravity에서 열고 다음과 같이 말하세요:

Read the README and configure TaroCub for me.
Use this Telegram bot token: <paste token>
Enable YOLO mode for my personal bot instance.

Lark의 경우, 다음과 같이 말하세요:

README를 읽고 나를 위해 Feishu/Lark 봇을 설정해줘.
Lark 위저드(wizard)를 실행하고, 권한을 확인하며, lark-cli를 설치/연결한 뒤, 내가 무엇을 스캔하거나 승인해야 하는지 알려줘.

이것이 권장되는 경로입니다. 각 단계를 직접 확인하고자 하는 운영자를 위한 수동 명령어도 아래에 있습니다.

@BotFather를 통해 Telegram 봇을 생성한 다음, 다음을 실행하세요:

git clone https://github.com/cloveric/tarocub.git
cd tarocub
npm install
...

telegram yolo unsafe

는 개인용 신뢰할 수 있는 봇 인스턴스를 위한 권장 기본 설정입니다. 이는 approvalMode: "bypass"로 매핑됩니다.

: Codex는 --dangerously-bypass-approvals-and-sandbox로 실행되고, Claude Code/Antigravity는 각각의 unsafe skip-permissions 플래그와 함께 실행되며, 브릿지는 매 턴마다 승인을 요청하지 않습니다. 이를 일반적인 승인 프롬프트와 로컬 샌드박스 (sandbox)를 우회하는 것과 동일하게 취급하십시오. telegram yolo off는 승인 프롬프트를 다시 명시적으로 사용하고 싶을 때만 사용하십시오.

봇에 아무 메시지나 보내세요. 봇이 페어링 코드 (pairing code)를 답장으로 보낼 것입니다:

npm run dev -- telegram access pair <pairing-code>

이제 Telegram에서 로컬 CLI 에이전트와 대화할 수 있습니다.

전체 Lark 네이티브 설정을 위해, 통합 설정 명령어가 lark-cli >= 1.0.41을 설치/연결하고, QR 위저드를 실행하며, 권한을 부여하고, 앱을 확인하도록 하세요:

npm install
npm run build
node dist/src/index.js lark setup --detached --install-cli --identity bot-only
...

--detached는 Telegram/Lark/Codex에서 설정할 때 권장됩니다. 이 옵션은 tmux에서 QR 등록 폴링 (polling)을 활성 상태로 유지하고, 지속 가능한 등록 링크 하나를 출력하며, 진행 상황을 ~/.cctb/<lark-instance>/lark-setup.log에 기록하고, 설정이 완료되면 Lark 서비스를 시작합니다. --no-start-service는 아직 리스닝 (listening)을 하지 않고 앱을 준비하기만 하고 싶을 때만 사용하십시오.

새로운 Telegram 및 Lark 봇 설정은 기본적으로 YOLO unsafe/bypass로 설정됩니다. 명시적인 lark yolo unsafe 명령어를 보여주는 이유는, 이것이 신뢰할 수 있는 개인용 봇에 대해 일반적인 승인 프롬프트와 로컬 샌드박싱을 우회함을 독자들이 이해하도록 하기 위함입니다.

lark doctor가

누락된 앱 스코프 (app scopes)를 보고하면, 출력된 권한 페이지 URL을 열고, 출력된 JSON을 일괄 가져오기 (bulk-import) 한 뒤, 앱 버전을 게시하고 다음을 실행하십시오:

node dist/src/index.js lark provision
node dist/src/index.js lark doctor

인터페이스 (Surface)	최적의 용도	상태
Telegram	모바일 제어, 음성 입력, 파일 전달, 멀티 봇 작업, cron, Agent Bus	기본 및 가장 심층적으로 테스트됨
Feishu/Lark	팀 채팅, 인터랙티브 카드, Docs 댓글, Sheets/Docs/Drive 워크플로우, 그룹/스레드 워크플로우	lark-cli를 통해 프로덕션 사용 가능
Local CLI	작업, 설정, 디버깅, 상태, 백업, 직접 전송	일급 운영자 인터페이스

주요 특징 (Highlight)	중요성
가짜 채팅 백엔드가 아닌 실제 CLI 엔진	Codex, Claude Code, Antigravity가 네이티브 로컬 CLI로 실행되므로, 실제 인증 (auth), 로컬 파일, 프로젝트 지침, MCP/플러그인 및 엔진 동작이 온전하게 유지됩니다.
세션 재개 (Session Resume)	처음부터 다시 시작하는 대신 기존 작업을 계속합니다: Claude 로컬 세션, Codex 스레드, Antigravity 대화를 채팅에서 연결하고 나중에 분리할 수 있습니다.
모바일 제어 평면으로서의 Telegram	휴대폰에서 에이전트와 대화하고, 파일 및 스크린샷을 보내고, 음성 메시지를 녹음하고, 작업을 승인하고, 멈춘 턴을 중단하고, 상태를 검사하며, 인스턴스를 재시작할 수 있습니다.
네이티브 작업 환경으로서의 Feishu/Lark	Lark는 Telegram이 할 수 없는 기능을 추가합니다: Card 2.0 선택, 승인 카드, Docs 댓글 @멘션, lark-cli를 통한 Sheets/Docs/Drive 워크플로우, /newgroup, 그리고 스레드를 인식하는 그룹 작업.
음성/오디오/비디오를 위한 ASR	Telegram 및 Lark의 음성/오디오/비디오 리소스를 다운로드하여 로컬에서 전사 (transcribe) 한 뒤, 일반적인 작업 컨텍스트로서 엔진에 전달할 수 있습니다.
파일 및 아티팩트 (artifact) 전달	에이전트는 구조화된 send.file, send.image, send.batch, 오디오 및 비디오 태그를 통해 생성된 이미지, PDF, 보고서, 덱 (decks), 소스 번들 및 기타 파일을 반환할 수 있습니다.

예약된 작업 및 리마인더 (Scheduled work and reminders) |
/cron 및 cron.add는 일회성 리마인더, 반복 작업, 에이전트 실행 예약 작업을 모델 메모리 외부에서 유지하며, 채팅/스레드 라우팅 (chat/thread routing)을 보존합니다. |
에이전트 버스 (Agent Bus) |
여러 봇 인스턴스가 위임 (delegation), 팬아웃 (fan-out), 체인 (chain), 검증기 (verifier), 그리고 코디네이터 주도 크루 워크플로우 (coordinator-led crew workflows)를 위한 로컬 워커 (local workers)로서 서로를 호출할 수 있습니다. |
미니 버스 (Mini Bus) |
Telegram 토픽이나 Lark 스레드가 경량화된 이름 기반 피어 (named peers)가 될 수 있으므로, 하나의 그룹 내에서 별도의 봇 없이도 플래너/라이터/리뷰어 (planner/writer/reviewer) 스타일의 워크플로우를 실행할 수 있습니다. |
보드 (Board) |
모델이 프로젝트 상태를 기억하는 것에 의존하는 대신, 작업, 의존성 (dependencies), 진행 중인 작업 (WIP), 리뷰 게이트 (review gates) 및 실행 이력을 위한 내구성이 있는 칸반 (Kanban) 상태를 제공합니다. |
검색 MCP (Search MCP) |
선택 사항인 Brave/Tavily MCP는 출처 추적이 가능한 web_search, web_extract, 제공자 상태, 폴백 (fallback) 알림 및 출처 로그를 제공합니다. |
운영 가시성 (Operational visibility) |
status, doctor, timeline, audit, dashboard, 사용량 추적, 서비스 잠금 (service locks) 및 백업을 통해 장애 발생 시 원인 불명의 상태가 아닌 조사 가능한 상태로 만듭니다. |

기능	Telegram	Feishu/Lark	로컬 CLI
Codex / Claude Code / Antigravity 엔진	예	예	예
...	프로비저닝/인증/doctor
타임라인, 감사, 대시보드, 사용량	예	예	주요 운영 인터페이스

Lark에는 두 가지 레벨이 있습니다:

레벨	작동 내용
SDK 전송 전용 (SDK transport only)	장기 연결 수신/송신, 액세스 체크, 일반 응답, 중지/승인 카드, 미디어 입력.
전체 Lark 네이티브 모드 (Full Lark-native mode)	Docs/Drive/Calendar/Sheets 작업, /newgroup, 문서 생성/자동 권한 부여, 사용자 OAuth, 더 풍부한 에이전트 워크플로우. lark-cli >= 1.0.41 필요.

권장되는 프로덕션 흐름:

# 각 이름이 지정된 Lark 봇에 대해 선택 사항이지만 권장됨:
export CCTB_LARK_INSTANCE=ccfgg1
node dist/src/index.js lark setup --detached --install-cli --identity bot-only
...

CCTB_LARK_INSTANCE=<name>

은 Lark 전용 인스턴스 선택기입니다. 명시적인 CCTB_LARK_STATE_DIR가 없으면, 해당 봇을 ~/.cctb/<name>/lark.env 아래에 저장합니다.

, 따라서 여러 개의 Feishu/Lark 봇이 공유 기본 디렉토리인 ~/.cctb/lark로 되돌아가지(fall back) 않도록 합니다.

lark setup 명령은 QR 위저드(wizard), lark-cli 사전 점검/바인딩(preflight/bind), 앱 프로비저닝(app provisioning), OAuth 상태 확인, lark doctor, 그리고 새 앱을 위한 서비스 시작 과정을 하나로 묶어 제공합니다. 채팅 기반 설정을 위해 --detached 옵션을 사용하면, 현재 에이전트 턴(agent turn)이 종료된 후에도 QR 위저드가 계속 실행됩니다. 이미 앱을 생성했으며 로컬 측만 다시 확인하고 싶은 경우, node dist/src/index.js lark setup --skip-wizard --install-cli --identity bot-only를 사용하세요. 리스너(listener)를 함께 시작하거나 재시작하려면 해당 재확인 명령에 --start-service를 추가하십시오.

유용한 Lark 명령:

node dist/src/index.js lark setup --detached --install-cli
node dist/src/index.js lark status
node dist/src/index.js lark permissions --missing
...

Lark 내부에서 봇은 Telegram과 동일한 핵심 슬래시(slash) 인터페이스를 지원합니다: /status, /usage, /engine, /model, /effort, /fast, /yolo, /goal, /resume, /detach, /stop, /reset, /cron, /board, /mini, /fan, /chain, /verify, /group, /invite, /remove, /ws, /newgroup, /newtopic, 그리고 /continue.

Lark 그룹/세션 의미론(semantics):

• 일반 그룹 채팅은 하나의 부모 그룹 세션(parent-group session)을 공유합니다. 일반 그룹 내에서 생성된 답글 스레드(reply threads)는 해당 스레드에 이미 명시적인 과거 세션 바인딩이 있지 않는 한 부모 그룹 세션에 머뭅니다.
• 토픽(Topic) 스타일의 Lark 그룹은 토픽당 하나의 세션을 사용합니다. 토픽 대화 키는 lark:<chat_id>:<thread_id>인 반면, 부모 그룹 키는 lark:<chat_id>입니다. /invite group 및 /group allow는 현재 스레드뿐만 아니라 현재 그룹 전체를 승인합니다. /remove group 및 /group deny는 현재 그룹 승인을 제거합니다. known-chats.json은 /status, /config 및 대시보드 라벨을 위한 진단 메타데이터입니다. 이 파일이 스스로 라우팅이나 액세스를 결정하지는 않습니다.

Lark 네이티브 컨트롤:

• 장시간 실행되는 (Long-running) Lark 턴은 이제 네이티브 진행 카드 (native progress card)를 전송하며, 사고 과정 (thinking), 도구 호출 (tool calls), 백그라운드 알림 (background notifications) 및 최종 결과로 해당 카드를 업데이트합니다. 최종 일반 답변 (plain reply)은 여전히 전달되므로, 기존 워크플로우가 카드에 의존하지 않습니다.
• 동일 대화 내 메시지는 기본적으로 보수적인 FIFO (First-In-First-Out) 큐잉 (queueing)을 사용합니다. CCTB_LARK_QUEUE_MODE=preempt, batch, 또는 preempt-batch로 명시적으로 활성화하지 않는 한 선택적 선점 (preempt) / 배치 (batch) 동작은 꺼져 있습니다. 배치 윈도우 (batch windows)는 CCTB_LARK_BATCH_WINDOW_MS=<ms>로 조정할 수 있습니다. /config는 카드 내에서 액세스 및 워크스페이스 가이드를 보여줍니다. /invite group, /remove group, /invite user @person, 그리고 /remove user @person은 안전한 인채팅 (in-chat) 액세스 제어 수단으로 유지됩니다. /ws list, /ws save <name> [absolute-path], /ws use <name>, 그리고 /ws remove <name>은 저장된 Lark 워크스페이스 디렉토리를 관리합니다. /ws use는 현재 대화 바인딩 (conversation binding)을 재설정하여, 워크스페이스 전환 시 오래된 프로젝트 컨텍스트 (project context)가 조용히 유지되지 않도록 합니다.

telegram service start --instance work
telegram service restart --all
telegram service status --all
...

lark service start
lark service restart
lark service restart --all
...

활성화된 Lark 턴 내부에서 lark service restart --all이 실행될 때, 현재 Lark 인스턴스는 지연되었다가 마지막에 재시작되어 봇이 자신의 프로세스를 중단하기 전에 답변을 완료할 수 있도록 합니다. Lark 봇 내부에서 Lark 인스턴스를 재시작하는 수동 쉘 루프 (hand-rolled shell loops)를 작성하는 것은 피하십시오.

명령어 그룹, Telegram/Lark 지원 및 예제에 대한 전체 슬래시 명령어 인덱스 (Slash Command Index)를 참조하십시오.

v0.1.40— Claude 어댑터를 통해 중간 [send-image:...] 태그를 보존하고, Feishu 이미지 전송이 실패할 경우 파일 전송으로 폴백 (fallback) 함으로써 Lark를 위한 Claude 생성 이미지 전달 문제를 수정했습니다.
v0.1.39— Lark 네이티브 UX를 심화했습니다: 스트리밍 실행 카드 (streaming run cards), 중지 가능한 큐 대기 카드 (stop-capable queue wait cards), 선택적 선점/배치 큐 모드 (기본값 꺼짐), 더 풍부한 텔레메트리 메트릭 (telemetry metrics), /config 액세스/워크스페이스 가이드, 그리고 /ws 지원.

workspace 프로필. v0.1.38— 읽기 시 기존 Lark known-chats.json 항목을 정화(sanitizes)하여, 답글 스레드(reply threads)에서 기록된 오래된 상위 그룹 레이블(parent-group labels)이 더 이상 /status, /config 또는 대시보드(dashboard)에서 혼동을 주지 않도록 합니다.

v0.1.37— Lark 그룹/토픽 UX를 강화합니다: 일반 그룹 답글 스레드가 토픽 세션(topic sessions)으로서 기존의 known-chat 레이블을 오염시키지 않으며, 권한이 없는 Lark 그룹 답글에는 이제 /invite group 또는 /group allow 안내가 포함됩니다.

v0.1.36— 플랫폼이 나중에 채팅 모드를 일반 그룹으로 보고하더라도 기존 Lark 스레드/토픽 세션을 보존하여, 활성화된 그룹 토픽이 재시작 후 이전 문맥(context)을 잊어버린 것처럼 보이는 현상을 방지합니다.

v0.1.35— Lark 서비스 종료/재시작 처리를 강화하여, tmux 정리(cleanup) 전에 직접적인 Node 프로세스 중단이 발생하도록 하고, 서비스 중단 후 재시작 시 오래된 잠금(stale locks)이 발생할 가능성을 줄입니다.

v0.1.34— Lark 관찰 가능성(observability) 및 제어 UX를 추가합니다: 선택 가능한 텔레메트리 어댑터(telemetry adapters), Lark 상태/재연결(health/reconnect) 이벤트, 선택적 공유 워커 풀링(shared worker pooling), /invite//remove