coleam00/remote-agentic-coding-system

Telegram, GitHub 등을 통해 AI 코딩 어시스턴트(Claude Code, Codex)를 원격으로 제어하세요. 지속적인 세션(Persistent sessions)과 유연한 워크플로우/시스템을 통해 어디서든 코딩하고자 하는 개발자들을 위해 구축되었습니다.

빠른 시작 (Quick Start): 핵심 설정 (Core Configuration) • AI 어시스턴트 설정 (AI Assistant Setup) • 플랫폼 설정 (Platform Setup) • 앱 시작 (Start the App) • 사용 가이드 (Usage Guide)

멀티 플랫폼 지원 (Multi-Platform Support): Telegram, GitHub 이슈/PR 등을 통해 상호작용하며, 향후 더 많은 플랫폼이 추가될 예정입니다.
다중 AI 어시스턴트 (Multiple AI Assistants): Claude Code 또는 Codex(또는 둘 다) 중에서 선택할 수 있습니다.
지속적인 세션 (Persistent Sessions): 세션이 컨테이너 재시작 후에도 유지되며 전체 컨텍스트(Context)를 보존합니다.
코드베이스 관리 (Codebase Management): 모든 GitHub 저장소(Repository)를 클론(Clone)하여 작업할 수 있습니다.
유연한 스트리밍 (Flexible Streaming): 플랫폼별로 실시간 또는 배치(Batch) 메시지 전달을 지원합니다.
범용 명령 시스템 (Generic Command System): Git으로 버전 관리되는 사용자 정의 명령을 지원합니다.
Docker 준비 완료 (Docker Ready): Docker Compose를 통한 간편한 배포가 가능합니다.

시스템 요구 사항 (System Requirements):

• Docker & Docker Compose (배포용)
• Node.js 20+ (로컬 개발용)

필요 계정 (Accounts Required):

• GitHub 계정 (/clone 명령어를 통한 저장소 클론용)
• 다음 중 최소 하나: Claude Pro/Max 구독 또는 Codex 계정
• 다음 중 최소 하나: Telegram 계정 또는 GitHub 계정 (상호작용용)

🌐 프로덕션 배포 (Production Deployment): 이 가이드는 로컬 개발 설정을 다룹니다. 클라우드 VPS(DigitalOcean, AWS, Linode 등)에서 24/7 운영을 위해 원격으로 배포하려면 **클라우드 배포 가이드 (Cloud Deployment Guide)**를 참조하세요.

시작하기 (Get started):

git clone https://github.com/coleam00/remote-agentic-coding-system
cd remote-agentic-coding-system

환경 파일 생성 (Create environment file):

cp .env.example .env

필수 변수 설정 (Set these required variables):

변수 (Variable)	용도 (Purpose)	획득 방법 (How to Get)
DATABASE_URL	PostgreSQL 연결	아래 데이터베이스 옵션 참조
GH_TOKEN	저장소 클론	repo 스코프(scope)로 토큰 생성
GITHUB_TOKEN	GH_TOKEN과 동일	동일한 토큰 값 사용
PORT	HTTP 서버 포트	기본값: 3000 (선택 사항)
WORKSPACE_PATH	클론 대상 경로	기본값: ./workspace (선택 사항)

GitHub 개인 액세스 토큰 설정 (GitHub Personal Access Token Setup):

• GitHub Settings > Personal Access Tokens 방문

• "Generate new token (classic)" 클릭 → 범위(scope) 선택:
  repo

• 토큰( ghp_... 로 시작)을 복사하고 두 변수를 모두 설정합니다:

# .env
GH_TOKEN=ghp_your_token_here
GITHUB_TOKEN=ghp_your_token_here # 동일한 값

데이터베이스 설정 (Database Setup) - 하나를 선택하세요:

옵션 A: 원격 PostgreSQL (Supabase, Neon)

원격 연결 문자열(connection string)을 설정합니다:

DATABASE_URL=postgresql://user:password@host:5432/dbname

첫 실행 후 마이그레이션(migrations)을 수동으로 실행합니다:

# 마이그레이션 파일을 다운로드하거나 psql을 직접 사용하세요
psql $DATABASE_URL < migrations/001_initial_schema.sql

이 작업은 다음 3개의 테이블을 생성합니다:

remote_agent_codebases

• 저장소 메타데이터 (Repository metadata)

remote_agent_conversations

• 플랫폼 대화 추적 (Platform conversation tracking)

remote_agent_sessions

• AI 세션 관리 (AI session management)

옵션 B: 로컬 PostgreSQL (Docker 사용)

자동 PostgreSQL 설정을 위해 with-db 프로필을 사용합니다:

DATABASE_URL=postgresql://postgres:postgres@postgres:5432/remote_coding_agent

docker compose --profile with-db로 시작하면 데이터베이스가 자동으로 생성됩니다.

최소 하나의 AI 어시스턴트를 구성해야 합니다. 원하는 경우 둘 다 구성할 수 있습니다.

🤖 Claude Code

OAuth 토큰 가져오기 (권장 방법):

# 먼저 Claude Code CLI를 설치하세요: https://docs.claude.com/claude-code/installation
claude setup-token
# sk-ant-oat01-... 으로 시작하는 토큰을 복사하세요

환경 변수 설정:

CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxx

대안: API 키 (사용량 기반 크레딧 결제를 선호하는 경우):

• console.anthropic.com/settings/keys 방문
• 새 키 생성 (sk-ant- 로 시작) - 환경 변수 설정:

CLAUDE_API_KEY=sk-ant-xxxxx

기본 어시스턴트로 설정 (선택 사항):

코드베이스 컨텍스트가 없는 새로운 대화에 대해 Claude를 기본 AI 어시스턴트로 사용하려면 다음 환경 변수를 설정하세요:

DEFAULT_AI_ASSISTANT=claude

🤖 Codex

Codex CLI로 인증:

# 먼저 Codex CLI를 설치하세요: https://docs.codex.com/installation
codex login
# 브라우저 인증 절차를 따르세요

인증 파일에서 자격 증명(credentials) 추출:

Linux/Mac의 경우:

cat ~/.codex/auth.json

Windows의 경우:

type %USERPROFILE%\.codex\auth.json

네 가지 환경 변수(environment variables) 모두 설정:

CODEX_ID_TOKEN=eyJhbGc...
CODEX_ACCESS_TOKEN=eyJhbGc...
CODEX_REFRESH_TOKEN=rt_...
...

기본 어시스턴트로 설정 (선택 사항):

코드베이스 컨텍스트(codebase context)가 없는 새로운 대화에서 Codex를 기본 AI 어시스턴트로 사용하려면 다음 환경 변수를 설정하세요:

DEFAULT_AI_ASSISTANT=codex

어시스턴트 선택 작동 방식:

• 어시스턴트 유형은 코드베이스별로 설정됩니다 (.claude/commands/ 또는 .codex/ 폴더에서 자동 감지됨)
• 대화가 시작되면 해당 대화에 대한 어시스턴트 유형은 고정됩니다
• DEFAULT_AI_ASSISTANT (선택 사항)는 코드베이스 컨텍스트가 없는 새로운 대화에서만 사용됩니다

AI 어시스턴트와 상호작용하려면 최소 하나의 플랫폼을 구성해야 합니다.

💬 Telegram

Telegram 봇 생성:

• Telegram에서 @BotFather에게 메시지를 보냅니다
• /newbot을 전송하고 안내를 따릅니다
• 봇 토큰(형식: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)을 복사합니다

환경 변수 설정:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHI...

스트리밍 모드(streaming mode) 구성 (선택 사항):

TELEGRAM_STREAMING_MODE=stream # stream (기본값) | batch

스트리밍 모드에 대한 자세한 내용은 고급 설정(Advanced Configuration)을 참조하세요.

🐙 GitHub Webhooks

요구 사항:

• 이슈(issues) 기능이 활성화된 GitHub 저장소
• 위 Core Configuration에서 이미 설정된 GITHUB_TOKEN
• Webhook을 위한 공개 엔드포인트(Public endpoint) (로컬 개발을 위한 ngrok 설정은 아래를 참조하세요)

1단계: Webhook Secret 생성

Linux/Mac의 경우:

openssl rand -hex 32

Windows (PowerShell)의 경우:

-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) })

이 Secret을 저장하세요. 3단계와 4단계에서 필요합니다.

2단계: 로컬 서버 노출 (개발 전용)

ngrok 사용 (무료 티어)

# ngrok 설치: https://ngrok.com/download
# 또는: choco install ngrok (Windows)
# 또는: brew install ngrok (Mac)
...

테스트하는 동안 이 터미널을 열어두세요.

Cloudflare Tunnel 사용 (지속적인 URL)

# 설치: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/
cloudflared tunnel --url http://localhost:3000
# Cloudflare 대시보드에서 지속적인 URL을 가져오세요

지속적인 URL (Persistent URLs)은 재시작 후에도 유지됩니다.

프로덕션 배포 (production deployments)의 경우, 배포된 서버 URL을 사용하세요 (터널이 필요하지 않음).

3단계: GitHub Webhook 설정

리포지토리 설정(repository settings)으로 이동하세요:

• 다음 경로로 이동:
  https://github.com/owner/repo/settings/hooks

• "Add webhook"을 클릭하세요.
  참고: 여러 리포지토리를 사용하는 경우, 각 리포지토리에 개별적으로 Webhook을 추가해야 합니다.

Webhook 설정:

필드	값
Payload URL	로컬: https://abc123.ngrok-free.app/webhooks/github 프로덕션: https://your-domain.com/webhooks/github
Content type	application/json
Secret	1단계에서 생성한 Secret을 붙여넣으세요
SSL verification	SSL 검증 활성화 (권장)
Events	"Let me select individual events" 선택: ✓ Issues ✓ Issue comments ✓ Pull requests

"Add webhook"을 클릭하고, 전송(delivery) 후 녹색 체크 표시가 나타나는지 확인하세요.

4단계: 환경 변수 (Environment Variables) 설정

WEBHOOK_SECRET=1단계에서 생성한_secret

중요: WEBHOOK_SECRET은 GitHub의 Webhook 설정에 입력한 값과 정확히 일치해야 합니다.

5단계: 스트리밍 (Streaming) 설정 (선택 사항)

GITHUB_STREAMING_MODE=batch # batch (기본값) | stream

스트리밍 모드에 대한 자세한 내용은 고급 설정 (Advanced Configuration)을 참조하세요.

사용법:

이슈(issues)나 풀 리퀘스트(PRs)에서 @remote-agent를 멘션(@mention)하여 상호작용하세요:

@remote-agent 이 버그를 분석해 줄 수 있어?
@remote-agent /command-invoke prime
@remote-agent 이 구현 내용을 리뷰해 줘

첫 번째 멘션 시 동작:

• 리포지토리를 /workspace로 자동 클론(clones)합니다.

• .claude/commands/ 또는 .agents/commands/에서 명령어를 감지하고 로드합니다.

• AI 어시스턴트(AI assistant)를 위해 이슈/PR(issue/PR)의 전체 컨텍스트(context)를 주입합니다.

이후 언급 시:

• 기존 대화를 재개합니다.
• 댓글(comments) 전반에 걸쳐 전체 컨텍스트(context)를 유지합니다.

데이터베이스 설정에 따라 Docker Compose 프로필(profile)을 선택하세요:

옵션 A: 원격 PostgreSQL 사용 (Supabase, Neon 등)

앱 컨테이너(app container)만 시작합니다 (.env 파일의 DATABASE_URL이 원격 데이터베이스로 설정되어 있어야 합니다):

# 앱 컨테이너 시작
docker compose --profile external-db up -d --build
# 로그 확인
...

옵션 B: 로컬 PostgreSQL 사용 (Docker)

앱과 PostgreSQL 컨테이너를 모두 시작합니다:

# 컨테이너 시작
docker compose --profile with-db up -d --build
# 시작 대기 (로그 확인)
...

옵션 C: 로컬 개발 (Docker 미사용)

Node.js로 직접 실행합니다 (로컬 PostgreSQL 또는 .env 파일의 원격 DATABASE_URL이 필요합니다):

npm run dev

애플리케이션 중지:

docker compose --profile external-db down # 옵션 A를 사용하는 경우
docker compose --profile with-db down # 옵션 B를 사용하는 경우

플랫폼 어댑터(platform adapter)가 실행되면 다음 명령어들을 사용할 수 있습니다:

명령어	설명	예시
/help	사용 가능한 명령어 표시	/help
/clone <url>	GitHub 리포지토리(repository) 클론(clone)	/clone https://github.com/user/repo
/repos	클론된 리포지토리 목록 표시	/repos
/status	대화 상태 표시	/status
/getcwd	현재 작업 디렉토리(current working directory) 표시	/getcwd
/setcwd <path>	작업 디렉토리 변경	/setcwd /workspace/repo
/command-set <name> <path>	커스텀 명령어(custom command) 등록	/command-set analyze .claude/commands/analyze.md
/load-commands <folder>	폴더에서 명령어를 일괄 로드	/load-commands .claude/commands
/command-invoke <name> [args]	커스텀 명령어 실행	/command-invoke plan "Add dark mode"
/commands	등록된 명령어 목록 표시	/commands
/reset	활성 세션 초기화	/reset

🚀 초기 설정

사용자: /clone https://github.com/anthropics/anthropic-sdk-typescript
봇: ✅ Repository (저장소) 복제가 성공적으로 완료되었습니다!
📁 Codebase (코드베이스): anthropic-sdk-typescript
...

💬 질문하기 (Asking Questions)

사용자: 이 저장소에는 어떤 파일들이 있나요?
봇: 📋 저장소 구조를 분석해 드릴게요...
[Claude가 상세 분석 내용을 스트리밍합니다]

🔧 명령어로 작업하기 (Working with Commands)

사용자: /command-invoke prime
봇: 🔍 코드베이스 조사를 시작합니다...
[Claude가 코드베이스 구조, 의존성(dependencies), 패턴을 분석합니다]
...

ℹ️ 상태 확인하기 (Checking Status)

사용자: /status
봇: 📊 대화 상태 (Conversation Status)
🤖 플랫폼 (Platform): telegram
...

🔄 세션 초기화 (Reset Session)

사용자: /reset
봇: ✅ 세션이 삭제되었습니다. 다음 메시지부터 새로 시작합니다.
📦 코드베이스 설정은 유지됩니다.

이슈(issue)를 생성하거나 기존 이슈/PR(Pull Request)에 댓글을 남기세요:

@your-bot-name 인증 흐름(authentication flow)을 이해하도록 도와줄 수 있나요?

봇이 분석 결과와 함께 응답합니다. 대화를 계속하세요:

@your-bot-name 이것을 위한 시퀀스 다이어그램(sequence diagram)을 작성해 줄 수 있나요?

봇이 문맥(context)을 유지하며 다이어그램을 제공합니다.

스트리밍 모드 설명 (Streaming Modes Explained)

AI가 응답을 생성함에 따라 메시지가 실시간으로 전송됩니다.

설정 (Configuration):

TELEGRAM_STREAMING_MODE=stream
GITHUB_STREAMING_MODE=stream

장점 (Pros):

• 실시간 피드백 및 진행 상황 표시
• 더 상호작용적이고 몰입감 있음
• AI의 추론(reasoning) 과정을 작업 중에 확인 가능

단점 (Cons):

• 플랫폼으로의 API 호출 증가
• 매우 긴 응답의 경우 속도 제한(rate limits)에 걸릴 수 있음
• 많은 메시지/댓글을 생성함

적합한 용도: 상호작용형 채팅 플랫폼 (Telegram)

AI가 처리를 완료한 후에만 최종 요약 메시지가 전송됩니다.

설정 (Configuration):

TELEGRAM_STREAMING_MODE=batch
GITHUB_STREAMING_MODE=batch

장점 (Pros):

• 단일하고 일관된 메시지/댓글
• 더 적은 API 호출
• 스팸이나 혼란 방지

단점 (Cons):

• 처리 중 진행 상황 표시 없음
• 첫 응답까지 대기 시간이 더 김
• 중간 단계를 볼 수 없음

적합한 용도: 이슈 트래커 및 비동기(async) 플랫폼 (GitHub)

동시성 설정 (Concurrency Settings)

시스템이 동시에 처리하는 대화의 수를 제어합니다:

MAX_CONCURRENT_CONVERSATIONS=10 # 기본값: 10

작동 방식:

• 대화는 잠금 관리자 (lock manager)를 통해 처리됩니다.
• 최대 동시성 제한에 도달하면, 새로운 메시지는 대기열 (queue)에 추가됩니다.
• 리소스 고갈 및 API 속도 제한 (rate limits)을 방지합니다.
• 각 대화는 자신만의 독립적인 컨텍스트 (context)를 유지합니다.

현재 부하 확인:

curl http://localhost:3000/health/concurrency

응답:

{
"status": "ok",
"active": 3,
...

튜닝 가이드:

• 리소스가 적은 경우: 3-5로 설정
• 표준: 기본값인 10이 적절함
• 리소스가 많은 경우: 20-30까지 증가 가능 (API 제한 모니터링 필요)

상태 확인 엔드포인트 (Health Check Endpoints)

애플리케이션은 모니터링을 위한 상태 확인 엔드포인트를 제공합니다:

기본 상태 확인 (Basic Health Check):

curl http://localhost:3000/health