Callabo Tmux 실행 스킬

Overview

Callabo 개발 서버들을 tmux 세션으로 한번에 실행하는 스킬입니다.

핵심 기능:

• 통합 실행: 4개 서비스를 하나의 tmux 세션으로 관리
• 자동 의존성 체크: .venv, node_modules 자동 설치
• AWS Vault 연동: 자동 인증 처리
• 세션 관리: 기존 세션 재접속 또는 재시작

Pane 구성:

┌─────────────────┬─────────────────┐
│ callabo-server  │   scheduler     │
│   (API/8000)    │ (scheduled_task)│
├─────────────────┼─────────────────┤
│ callabo-webapp  │      magi       │
│   (Next.js)     │   (pnpm dev)    │
└─────────────────┴─────────────────┘

When to Use

이 스킬은 다음 상황에서 자동으로 활성화됩니다:

명시적 요청:

• "콜라보 서버 실행해줘"
• "callabo 띄워줘"
• "개발 서버 시작해줘"
• "tmux로 콜라보 실행해줘"
• "작업 환경 띄워줘"

자동 활성화:

• callabo-init으로 생성한 워크스페이스 실행 시
• 개발 작업 시작 전

Prerequisites

필수 도구

# tmux
tmux -V

# uv (Python)
uv --version

# yarn 또는 pnpm
yarn --version
pnpm --version

# AWS Vault (선택)
aws-vault --version

워크스페이스 구조

실행할 디렉토리에 다음 구조가 필요:

<workspace>/
├── callabo-server/
│   ├── .env
│   ├── .venv/        # 자동 생성
│   └── asgi.py
├── callabo-webapp/
│   ├── .env
│   └── node_modules/ # 자동 설치
├── magi/
│   ├── .env
│   └── node_modules/ # 자동 설치
└── run.sh

Workflow

Step 1: 워크스페이스 확인

# 워크스페이스 경로 확인
ls -la <workspace>/

# 필수 디렉토리 확인
ls callabo-server/ callabo-webapp/ magi/

Step 2: 실행 스크립트 호출

# 스킬 내장 스크립트 경로
SKILL_SCRIPT="./scripts/run.sh"

# 기본 실행 (AWS Vault 비밀번호 자동 입력)
echo "" | $SKILL_SCRIPT <workspace>

# 현재 디렉토리에서 실행
echo "" | $SKILL_SCRIPT .

# AWS Vault 건너뛰기 (로컬 전용)
CALLABO_SKIP_AWS_VAULT=1 $SKILL_SCRIPT <workspace>

Note: echo "" |는 AWS Vault 비밀번호 프롬프트에 빈 문자열(엔터)을 자동 입력합니다.

Step 3: 옵션 설정

옵션	설명	예시
--name NAME	tmux 세션 이름	--name my-callabo
-f, --force	기존 세션 종료 후 재시작	-f
--force-sync	의존성 강제 재설치	--force-sync
--skip-scheduler	스케줄러 pane 생성 안 함	--skip-scheduler
--with-scheduler	스케줄러 강제 활성화	--with-scheduler

Step 4: 세션 관리

# 세션 목록 확인
tmux ls

# 세션 접속
tmux attach -t <session-name>

# 세션 분리 (tmux 내에서)
Ctrl+b, d

# 세션 종료
tmux kill-session -t <session-name>

---

Examples

예시 1: 기본 실행

사용자: 콜라보 서버 띄워줘

Claude: Callabo 개발 서버를 시작하겠습니다.

📍 현재 워크스페이스: ~/work/feature-login

[명령 실행]
echo "" | ./scripts/run.sh ~/work/feature-login

✅ tmux 세션 'runtime-feature-login' 이(가) 준비되었습니다.

접속 명령:
tmux attach -t runtime-feature-login

실행 중인 서비스:
- callabo-server: http://localhost:8000
- callabo-webapp: http://localhost:3000
- magi: http://localhost:3200
- scheduler: 백그라운드 실행 중

예시 2: 커스텀 세션명으로 실행

사용자: my-dev라는 이름으로 콜라보 띄워줘

Claude: 커스텀 세션명으로 실행하겠습니다.

[명령 실행]
echo "" | ./scripts/run.sh . --name my-dev

✅ tmux 세션 'my-dev' 생성 완료

Pane 구성:
┌─────────────┬─────────────┐
│   server    │  scheduler  │
├─────────────┼─────────────┤
│   webapp    │    magi     │
└─────────────┴─────────────┘

예시 3: 기존 세션 강제 재시작

사용자: 콜라보 세션 다시 시작해줘

Claude: 기존 세션을 종료하고 재시작하겠습니다.

[명령 실행]
echo "" | ./scripts/run.sh . --force

기존 tmux 세션 'runtime-feature-login' 종료를 시도합니다...
기존 tmux 세션 'runtime-feature-login' 이(가) 정상적으로 종료되었습니다.
✅ 새 세션 시작 완료

예시 4: 스케줄러 없이 실행

사용자: 스케줄러 빼고 띄워줘

Claude: 스케줄러 없이 실행하겠습니다.

[명령 실행]
echo "" | ./scripts/run.sh . --skip-scheduler

✅ 세션 준비 완료 (scheduler 제외)

Pane 구성:
┌─────────────┬─────────────┐
│   server    │  (skipped)  │
├─────────────┼─────────────┤
│   webapp    │    magi     │
└─────────────┴─────────────┘

예시 5: 의존성 강제 재설치 후 실행

사용자: 의존성 다시 설치하고 띄워줘

Claude: 의존성을 재설치 후 실행하겠습니다.

[명령 실행]
echo "" | ./scripts/run.sh . --force-sync

[callabo-server] CALLABO_FORCE_SYNC=1: uv sync를 강제로 실행합니다...
[callabo-webapp] yarn install을 실행합니다...
[magi] pnpm install을 실행합니다...

✅ 의존성 설치 완료
✅ 세션 시작 완료

예시 6: 다른 워크스페이스 실행

사용자: ~/work/other-feature 워크스페이스 띄워줘

Claude: 지정된 워크스페이스를 실행하겠습니다.

[명령 실행]
echo "" | ./scripts/run.sh ~/work/other-feature

✅ tmux 세션 'runtime-other-feature' 준비 완료

접속: tmux attach -t runtime-other-feature

---

Configuration

환경 변수

변수	설명	기본값
AWS_VAULT_PROFILE	AWS Vault 프로파일	dev-callabo
AWS_VAULT_PASS	AWS Vault 비밀번호 (빈 문자열이면 자동 엔터)	""
CALLABO_SKIP_AWS_VAULT	AWS Vault 건너뛰기	미설정
CALLABO_FORCE_SYNC	강제 의존성 설치	0
CALLABO_SKIP_SCHEDULER	스케줄러 비활성화	0
CALLABO_FORCE_SHUTDOWN_TIMEOUT	종료 대기 시간(초)	15

AWS Vault 자동 인증 (기본값):

# AWS_VAULT_PASS가 설정되면 자동으로 비밀번호 입력
# 빈 비밀번호인 경우 (기본값)
AWS_VAULT_PASS="" ./run.sh

# 비밀번호가 있는 경우
AWS_VAULT_PASS="<your-password>" ./run.sh

포트 설정

각 서비스의 포트는 .env 파일에서 설정:

# callabo-server/.env
PORT=8000
UVICORN_PORT=8000

# callabo-webapp/.env
PORT=3000

# magi/.env
PORT=3200

세션 이름 규칙

--name 미지정 시 자동 생성:

runtime-{현재디렉토리이름}

예시:

• ~/work/feature-login → runtime-feature-login
• ~/callabo-base → runtime-callabo-base

---

Tmux 단축키

세션 내에서 유용한 단축키:

단축키	설명
Ctrl+b, d	세션 분리 (detach)
Ctrl+b, o	다음 pane으로 이동
Ctrl+b, ;	이전 pane으로 이동
Ctrl+b, 방향키	해당 방향 pane으로 이동
Ctrl+b, z	현재 pane 확대/축소
Ctrl+b, [	스크롤 모드 진입
q	스크롤 모드 종료
Ctrl+c	현재 pane 프로세스 중단

---

Best Practices

DO:

• 작업 전 기존 세션 확인 (tmux ls)
• 세션명을 기억하기 쉽게 지정
• 문제 발생 시 --force로 깨끗하게 재시작
• 의존성 문제 시 --force-sync 사용

DON'T:

• 같은 워크스페이스에 여러 세션 실행
• 프로세스 강제 종료 대신 graceful shutdown 사용
• AWS Vault 없이 실서버 연동 시도

---

Troubleshooting

tmux 세션 접속 안 됨

# 세션 존재 확인
tmux has-session -t <session-name>

# 세션 목록
tmux ls

# 모든 세션 종료 후 재시작
tmux kill-server
./run.sh

AWS Vault 인증 오류

# AWS Vault 프로파일 확인
aws-vault list

# 수동 인증
aws-vault exec dev-callabo -- ./run.sh

# AWS Vault 건너뛰기 (로컬 전용)
CALLABO_SKIP_AWS_VAULT=1 ./run.sh

포트 이미 사용 중

# 포트 사용 프로세스 확인
lsof -i :8000
lsof -i :3000
lsof -i :3200

# 프로세스 종료
kill -9 <PID>

# 또는 기존 세션 강제 종료 후 재시작
./run.sh --force

.venv 손상됨

# 강제 재설치
./run.sh --force-sync

# 또는 수동 재설치
cd callabo-server
rm -rf .venv
uv sync

Pane이 바로 종료됨

# 로그 확인
# 각 서비스 디렉토리에서 직접 실행하여 에러 확인

# callabo-server
cd callabo-server && .venv/bin/python -m uvicorn asgi:app

# callabo-webapp
cd callabo-webapp && yarn dev

# magi
cd magi && pnpm dev

---

Integration

이 스킬은 다음 스킬과 연동됩니다:

스킬	연동 방식
callabo-init	생성된 워크스페이스 실행
context-worktree	워크스페이스 전환 시 실행

callabo-init과의 워크플로우

┌─────────────────────────────────────────────────────────────┐
│ 일반적인 개발 시작 흐름:                                     │
│                                                             │
│ [callabo-init] ──────────────────> [callabo-tmux]           │
│     │                                   │                   │
│     │ 워크스페이스 생성                  │ 서비스 실행       │
│     │ - 레포 클론                        │ - tmux 세션      │
│     │ - 브랜치 생성                      │ - 4개 pane       │
│     │ - .env 설정                        │ - 의존성 체크    │
│     │ - 포트 연동                        │                   │
│     ▼                                   ▼                   │
│  ~/work/feature-x/              runtime-feature-x 세션      │
└─────────────────────────────────────────────────────────────┘

연속 사용 예시:

사용자: 새 기능 개발 시작할게. 워크스페이스 만들고 서버 띄워줘

Claude:
1. [callabo-init 활성화]
   워크스페이스 생성 중...
   ./scripts/init-callabo-workspace.sh ~/work/new-feature feature/new
   ✅ 완료

2. [callabo-tmux 활성화]
   서비스 시작 중...
   echo "" | ./scripts/run.sh ~/work/new-feature
   ✅ tmux 세션 'runtime-new-feature' 준비됨

context-worktree와의 연동

context-worktree가 활성화된 경우:

• 워크스페이스 전환 시 해당 워크스페이스의 tmux 세션 상태 확인
• 세션이 없으면 자동으로 callabo-tmux 실행 제안
• 세션이 있으면 기존 세션에 접속 안내

사용자: ~/work/other-feature로 전환해줘

Claude: [context-worktree + callabo-tmux 연동]
워크스페이스 전환: ~/work/other-feature

tmux 세션 'runtime-other-feature'가 존재하지 않습니다.
서비스를 시작할까요? [Y/n]

---

Resources

항목	경로
실행 스크립트	./scripts/run.sh
서버 코드	<workspace>/callabo-server/
웹앱 코드	<workspace>/callabo-webapp/
Magi 코드	<workspace>/magi/