COKACDIR — 텔레그램으로 Claude Code, Codex CLI를 원격 제어하는 법

안녕하세요, 자바파커입니다.

"Claude Code를 쓰고 싶은데, 항상 컴퓨터 앞에 앉아 있을 수는 없잖아요."

AI 코딩 에이전트를 써보면 한 가지 아쉬운 점이 있습니다. 내 컴퓨터 터미널에서만 쓸 수 있다는 것. 외출 중에 "아 그 버그 고쳐야 하는데" 싶어도, 노트북을 열 수 없으면 답이 없습니다.

결론부터 말씀드리면 — COKACDIR을 쓰면 텔레그램 메시지 하나로 내 컴퓨터의 Claude Code를 원격 조작할 수 있습니다. 새로운 AI를 설치하는 게 아니라, 이미 쓰고 있는 코딩 에이전트를 텔레그램에서 리모컨처럼 조종하는 방식입니다.

저는 실제로 사내에서 봇 2개를 만들어 각각 Claude Code와 Codex CLI를 연결하고, 하나의 그룹에서 "작성 → 검증" 역할을 나눠 운영하고 있습니다. 직접 써본 경험까지 공유합니다.

---

COKACDIR이 뭔가?

COKACDIR(코칵디르)은 기존 AI 코딩 에이전트를 텔레그램에서 원격 제어하게 해주는 오픈소스 도구입니다.

핵심 컨셉을 정리하면:

항목	내용
정체	AI 코딩 에이전트 원격 제어 도구
지원 에이전트	Claude Code, Codex CLI, Gemini CLI, OpenCode
조작 방식	텔레그램 봇
기술 스택	Rust 74.7%, TypeScript 22.6%
바이너리 크기	15~20MB (단일 바이너리)
라이선스	MIT
GitHub	kstost/cokacdir

비유하자면 — Claude Code가 내 컴퓨터에서 일하는 AI 개발자라면, COKACDIR은 그 개발자에게 텔레그램으로 업무 지시를 보내는 채널입니다. AI 자체가 아니라, 기존 AI에 리모컨을 달아주는 도구입니다.

---

왜 필요한가?

기존 방식의 한계

Claude Code, Codex CLI 같은 코딩 에이전트는 강력하지만, 내 컴퓨터 터미널에 직접 접속해야 합니다.

상황	기존 방식	COKACDIR
외출 중 긴급 버그 수정	노트북 필요	텔레그램에서 지시
장시간 작업 모니터링	터미널 열어둬야 함	텔레그램으로 실시간 확인
예약 작업 (야간 빌드 등)	별도 CI/CD 구성	cron 표현식으로 예약
팀원과 AI 공유	각자 설치 필요	그룹 채팅에서 공유 사용

특히 스마트폰 하나로 AI 코딩 에이전트를 제어할 수 있다는 점이 핵심입니다.

---

설치 방법 — 5분 가이드

Step 1: COKACDIR 설치

macOS / Linux:

curl -fsSL https://cokacdir.cokac.com/manage.sh | bash && cokacctl

Windows (관리자 PowerShell):

irm https://cokacdir.cokac.com/manage.ps1 | iex; cokacctl

설치하면 cokacctl이라는 관리 TUI가 열립니다.

Step 2: 텔레그램 봇 생성

1. 텔레그램에서 @BotFather를 검색
2. /newbot 명령 입력
3. 봇 이름과 아이디 설정
4. API 토큰을 복사 (예: 123456789:ABCdefGhIjKlmNoPqRsTuVwXyZ)

Step 3: COKACDIR 설정

cokacctl TUI에서:

1. i 키 — 설치
2. 복사한 텔레그램 봇 토큰 입력
3. s 키 — 서버 시작

이 3단계면 끝입니다. 이제 텔레그램에서 내가 만든 봇에게 메시지를 보내면, 내 컴퓨터의 코딩 에이전트가 작업을 수행합니다.

---

주요 기능

1. 텔레그램에서 코딩 에이전트 제어

텔레그램 봇에게 자연어로 메시지를 보내면, 연결된 코딩 에이전트(Claude Code 등)가 실행합니다.

나: src/api/auth.js에서 JWT 만료 시간을 1시간에서 24시간으로 변경해줘

봇: [Claude Code 실행 중...]
     auth.js 파일을 수정했습니다.
     - expiresIn: '1h' → '24h'
     변경 완료.

실시간 스트리밍으로 진행 상황을 확인할 수 있습니다.

2. 멀티 에이전트 지원

하나의 COKACDIR에서 여러 코딩 에이전트를 전환할 수 있습니다.

명령어	설명
/model	사용할 에이전트/모델 전환
/session	세션 관리
/start	세션 시작
/stop	세션 중지
/clear	대화 초기화

3. 예약 작업

cron 표현식이나 절대 시간으로 작업을 예약할 수 있습니다. 야간 빌드, 정기 코드 점검 같은 반복 작업에 유용합니다.

4. 파일 업로드/다운로드

텔레그램으로 파일을 보내면 서버에 업로드되고, /down 명령으로 서버의 파일을 텔레그램으로 받을 수 있습니다.

5. 보안 기능

기능	설명
AES-256 암호화	설정 가능한 청크 분할로 파일 암호화
접근 제어	/allowed로 허용 사용자 관리
도구 제한	/allowedtools로 사용 가능한 도구 제어

---

추가 기능 — 코딩 에이전트 외

COKACDIR은 원격 코딩 제어 외에도 부가 기능을 제공합니다.

기능	설명
터미널 멀티패널	분할 화면으로 여러 작업 동시 수행
20+ 언어 구문 강조	코드 파일 내장 뷰어
이미지 뷰어	Kitty, iTerm2, Sixel 프로토콜 지원
Git 통합	상태, 커밋, 로그, 브랜치 관리
SSH/SFTP	원격 서버 접속
중복 파일 감지	디스크 정리 도구
프로세스 관리자	실행 중인 프로세스 모니터링

---

지원 플랫폼

OS	아키텍처
macOS	Apple Silicon (ARM64), Intel (x86_64)
Linux	x86_64, ARM64
Windows	x86_64, ARM64

Rust로 작성되어 단일 바이너리(15~20MB)로 배포됩니다. 별도 런타임 설치 없이 바로 실행할 수 있습니다.

---

실전 활용 — 직접 써본 경험

멀티봇 협업 구조: AI 2대를 한 그룹에서 굴리기

저는 사내에서 COKACDIR 봇 2개를 운영하고 있습니다. 각 봇에 서로 다른 코딩 에이전트를 연결하고, 하나의 텔레그램 그룹에 초대해서 역할을 분리했습니다.

봇	연결 에이전트	역할
Bot A	Claude Code	코드 작성, 아키텍처 설계, 리팩토링
Bot B	Codex CLI / Gemini CLI	코드 리뷰, 테스트 작성, 검증

작업 흐름은 이렇습니다:

[텔레그램 그룹]

나: @BotA 사용자 인증 API를 만들어줘. 
    JWT 기반, refresh token 포함.

Bot A (Claude Code): 
    인증 API를 작성했습니다.
    - POST /auth/login
    - POST /auth/refresh
    - POST /auth/logout
    파일 3개 생성 완료.

나: @BotB 방금 Bot A가 만든 인증 API 코드를 리뷰해줘.
    보안 취약점이 있는지 확인하고, 테스트도 작성해줘.

Bot B (Codex CLI):
    리뷰 완료. 2가지 개선사항:
    1. refresh token 저장 시 해싱 필요
    2. rate limiting 미적용
    테스트 파일 생성 완료 (12 cases).

나: @BotA 리뷰 반영해서 수정해줘.

Bot A: 수정 완료. 모든 테스트 통과.

핵심은 "작성 → 검증 → 수정"을 서로 다른 AI가 맡는다는 점입니다. 한 AI가 만든 코드를 다른 AI가 검증하면, 한 AI에게 모든 걸 맡기는 것보다 완성도가 확실히 올라갑니다. 사람이 하는 코드 리뷰 프로세스와 똑같은 구조를 AI끼리 돌리는 셈입니다.

이 구조의 장점

1. 크로스 체크: AI도 실수합니다. 다른 모델이 검증하면 놓치는 부분을 잡아냅니다
2. 역할 특화: Claude Code는 코드 생성이 강하고, Codex는 테스트 작성에 능합니다. 각자 잘하는 일을 맡기면 효율적입니다
3. 한 그룹에서 관리: 팀원 모두가 대화 흐름을 볼 수 있고, 중간에 개입할 수 있습니다
4. 기록 자동 보관: 텔레그램 채팅 기록이 곧 작업 로그입니다

기타 활용 시나리오

외출 중 긴급 핫픽스:

나: production에서 /api/users 500 에러. 로그 확인하고 수정해줘.
봇: null 참조 에러 확인. 수정 완료. 커밋할까요?
나: 응
봇: 푸시 완료.

야간 자동 작업:

cron 표현식으로 매일 새벽 2시에 테스트를 실행하고 결과를 텔레그램으로 받을 수 있습니다.

팀 공유:

텔레그램 그룹에 봇을 추가하면 팀원 모두가 AI 에이전트를 사용할 수 있습니다. /allowed 명령으로 접근 권한을 관리합니다.

---

주의할 점

1. 보안: 내 컴퓨터에서 AI가 직접 실행되므로, 봇 토큰 관리와 접근 제어(/allowed)를 반드시 설정하세요
2. 비용: COKACDIR 자체는 무료지만, 연결하는 코딩 에이전트(Claude Code 등)의 사용 요금은 별도입니다
3. 컴퓨터 상태: 내 컴퓨터가 켜져 있고 인터넷에 연결되어 있어야 합니다
4. MIT 라이선스: 소프트웨어는 "AS IS"로 제공되며, 데이터 손실 등에 대한 책임은 사용자에게 있습니다

---

정리

항목	내용
한 줄 요약	텔레그램으로 Claude Code/Codex/Gemini를 원격 제어
추천 대상	이동 중에도 AI 코딩을 사용하고 싶은 개발자
비용	COKACDIR 무료, 에이전트 비용 별도
설치 시간	약 5분
GitHub	kstost/cokacdir

"AI 코딩 에이전트는 좋은데 항상 컴퓨터 앞에 있어야 한다"는 불편함을 정확히 해결하는 도구입니다. 특히 Claude Code를 주력으로 쓰는 개발자라면, 텔레그램 봇 하나 만들어두는 것만으로 활용도가 크게 올라갑니다.

---

FAQ

Q. Claude Code가 설치되어 있어야 하나요?

네. COKACDIR은 새로운 AI가 아니라, 기존에 설치된 코딩 에이전트의 리모컨 역할입니다. Claude Code, Codex CLI, Gemini CLI 중 하나 이상이 설치되어 있어야 합니다.

Q. 컴퓨터를 끄면 어떻게 되나요?

COKACDIR 서버가 꺼지므로 텔레그램에서 제어할 수 없습니다. 항상 접근하려면 클라우드 서버(AWS, GCP 등)에 설치하는 것을 추천합니다.

Q. 보안은 안전한가요?

텔레그램 봇 토큰과 /allowed 명령으로 접근을 제한할 수 있습니다. 다만 내 컴퓨터에서 AI가 직접 명령을 실행하므로, 봇 토큰 유출에 주의해야 합니다. AES-256 파일 암호화도 지원합니다.

---

여러분은 AI 코딩 에이전트를 어떻게 원격으로 활용하고 계신가요? 다른 방법을 쓰고 계시다면 댓글로 공유해주세요!