tg-cli

tg-cli(명령어명 tg)는 AI 코딩 에이전을 위한 텔레그램 브릿지입니다. 두 가지 구성 요소로 나뉩니다: 에이전트가 호출하여 업데이트를 푸시하는 아웃바운드 CLI와, 전화에서의 reply를 실행 중인 에이전트 세션으로 전달하는 인바운드 데몬인 tg-ctl입니다. 아웃바운드. 에이전트는 텍스트, HTML 보고서, 사진 및 파일을 전송합니다. HTML 태그가 자동 감지되며 감지된 에이전트에 대한 브랜드 이모지 접두사가 추가됩니다. Markdown 파일은 업로드 전에 pandoc과 헤드리스 크롬을 통해 PDF로 변환되며, 변환 실패 시 원래 파일이 전송됩니다. 메시지 텍스트에 언급된 파일 경로가 워크트리 전반에 대한 재귀 검색을 통해 자동으로 감지되어 첨부되며, 경로는 캡션에 남습니다. 보내기 전에 여러 가드 기능이 실행됩니다. 여섯 개 이상의 텔레그램 전송으로 분할될 만큼 긴 메시지는 문자 수와 분할 수와 함께 거부됩니다. 비서적으로 보이는 파일(.env 파일, SSH 개인 키, pem/key/p12/pfx/ppk, 자격 증명 rc파일, 셸 히스토리, tfvars, credentials.json, kubeconfig)은 절대 첨부되지 않으며, 자동 감지된 언급은 건너뛰고 명시적 파일 인수는 hard error입니다. 가려운 토큰 가드는 라틴 또는 키릴 문자 단어 안에 고립된 CJK 코드포인트와 스크립트가 두 번 이상 전환되는 토큰을 차단하지만, 진정하게 이국어 텍스트는 허용합니다. 스크린샷 가드는 사진 없이 스크린샷을 언급하는 메시지를 거부합니다. 사전 가드는 사용자가 관리하는 JSON 파일의 금지된 어휘를 모든 보내기 항목의 제목, 본문, 캡션과 일치시키며 설계상 우회 플래그가 없으며, malformed 파일은 닫힌 상태로 실패합니다. Autolinks는 Linear CLI를 통해 Linear 티켓 ID를, gh를 통해 GitHub PR/이슈 번호를 해석하며 결과를 1시간 동안 캐시하고plain text로 저하됩니다. no-feature 플래그로 개별 기능을 끌 수 있습니다. 인바운드. tg-ctl은 감지된 에이전트가 있는 tmux 창에서 첫 번째 아웃바운드 보내기 시 자동으로 시작됩니다. 텔레그램에서 온 plain text reply가 해당 에이전트 창에 주입됩니다. 메시지를 인용하여 답하면 인용 앵커가 첨부되어 tg replies 명령으로 전체 원문을 가져올 수 있습니다. /agent 명령은 모호할 때 세션별로 그룹화된 선택 버튼을 제공하며, bare invocation은 에이전트 목록을 출력합니다. tmux 외부에서 시작한 에이전트는 창이 없으며, 원인 설명과 함께 도달할 수 없는 것으로 표시되고 Stop-hook inbox를 통해 두 번째 채널을 얻으며, 이는 매 턴 종료 시 읽힙니다. README는 제한 사항을 명시적으로 서술합니다: 이미 대기 중인 에이전트는 다음 턴을 마칠 때만 대기 메시지를 받습니다. tg-ctl inbox 명령은 대기 중인 내용을 보여줍니다. Question-to-buttons는 에이전트의 질문과 권한 프롬프트를 Telegram의 inline buttons로 전달하여 탭하여 답하면 답이 창에 직접 주입됩니다. Claude Code 질문/권한 형식, Codex PermissionRequest 및 opencode question.asked/permission.asked 이벤트를 처리하며, install-hooks 명령으로 idempotently 연결되어 기존 설정을 백업하고 보존합니다. 질문 대기 중 전송된 메시지는 프롬프트를 방해하지 않고 연기되며, 시간 초과된 질문 카드도 plain text로 응답할 수 있습니다. 명령에는 stop(현재 턴 인터럽트), kill, status, limit(에이전트별 최신 사용량 telemetry), tasks(필터 가능한 작업 대시보드), agent, daily(출하 작업 보고서), spend(토큰 및 비용 사용량)가 포함됩니다. 텔레그램에서 전송된 사진과 문서는 로컬 캐시 디렉터리에 다운로드되어 에이전트가 읽을 수 있도록 경로가 주입됩니다. Claude Code statusLine, Codex 토큰 수, Pi 세션 통계에서 파이프된 사용량 telemetry는 제한이 90%에 도달할 때 중복 제거 경고로 트리거될 수 있습니다. Forum-topic 라우팅은 opt-in이며 실험적이며, 주제 생성이 에이전트 생성을 유발하고 활성화된 주제를 다시 여는 것이 에이전트 재연결을 하지 않는다는 문서화된 주의 사항이 있습니다. control은 구성 파일에서 비활성화할 수 있습니다. 설치. 원라인 설치 스크립트는 Bun을 통해 의존성을 설치하고 tg를 PATH에 링크하며 에이전트 스킬을 등록합니다. 수동 clone + symlink로도 작동합니다. 구성은 bot token과 chat id가 있는 config 디렉터리 아래의 dotenv 파일에 있습니다. install-skill subcommand는 스킬 파일을 작성하고 감지된 harness 파일에 short instructions를 추가합니다. 체크아웃된 스크립트가 실행 파일이므로 빌드 단계가 없으며, deploy 스크립트는 로컬 변경사항을 pull하지 않고 fast-forward로 체크아웃을 업데이트합니다. 데몬 코드 변경사항은 재시작이 필요하며 스크립트가 이를 감지하여 보고합니다. 머신당 하나의 bot token이 필요합니다. Telegram은 토큰당 단일 getUpdates 소비자만 허용합니다.