name: callabo-tmux description: Callabo 서비스들을 tmux로 한번에 실행합니다. callabo-server, scheduler, callabo-webapp, magi를 4개의 pane으로 구성하여 개발 환경을 빠르게 시작합니다. trigger_keywords:

콜라보 실행
callabo 실행
콜라보 띄워
callabo run
개발 서버 시작
tmux 콜라보
작업 환경 띄워
서버 띄워

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/`

callabo-tmux

$ 설치