Paseo 사용설명서: 여러 AI 코딩 에이전트를 한 번에 굴리는 작업실 앱
Claude Code·Codex·OpenCode 등 여러 AI 코딩 에이전트를 Git 워크트리로 병렬 실행하고 모바일·CLI·서버에서 제어하는 Paseo(paseo.sh) 완벽 가이드. 설치, paseo.json, 스킬·오케스트레이션, 문제 해결까지 정리했습니다.
목차
- 1. Paseo가 정확히 뭐예요? & 준비물
- 2. 설치하기 — 세 가지 방법
- 3. 꼭 알아야 할 세 단어: 프로젝트 · 워크스페이스 · 세션
- 4. 병렬 워크트리 실전과 paseo.json 설정
- 5. 결과 검증·모바일 이어하기·CLI 7대 명령
- 6. AI에게 AI를 시키기 (오케스트레이션 · 스킬 · 플러그인)
- 7. 자주 막히는 곳 (증상별 문제 해결 탐색기)
- 8. 자주 묻는 질문 (FAQ)과 용어 사전
1. Paseo가 정확히 뭐예요? & 준비물
요즘 Claude Code, Codex, OpenCode, Cursor, Gemini CLI 같은 코딩 에이전트는 파일을 읽고 고치며 테스트까지 돌립니다. 문제는 터미널 창 하나에 하나씩 갇혀 있어 두 가지 일을 동시에 시키면 창이 뒤섞이고 결과를 놓치기 쉽다는 점입니다.
- 헷갈리지 마세요: Paseo는 AI 모델이 아닙니다. 이미 설치하고 로그인해 둔 CLI 도구(
claude,codex,opencode등 40여 종)를 불러다 실행하는 작업실 껍데기이므로 기존 구독·설정·MCP 서버·스킬이 그대로 유지됩니다.
시작하기 전 준비물
| 준비물 | 설명 |
|---|---|
| AI 코딩 CLI 1개 이상 | Claude Code, Codex, OpenCode, Pi, Antigravity, Muse Code 등을 직접 설치하고 로그인까지 완료 (claude나 codex를 터미널에서 쳐서 대화가 시작되면 준비 끝) |
| Git + 프로젝트 폴더 | 병렬 작업의 핵심이 Git 워크트리이므로 Git 저장소가 사실상 필수 |
GitHub CLI (gh, 권장) | 로그인해 두면 PR 단위로 작업 공간을 열거나 PR 상태를 인식 가능 |
| Node.js (CLI 설치 시) | 데스크톱 앱만 쓴다면 별도 설치 불필요 |
2. 설치하기 — 세 가지 방법
데스크톱 앱 (★☆☆)처음이라면 100% 추천 — 데몬 내장
“내려받고 열기만 하면 끝”
- 설치 방법
- paseo.sh/download 또는 GitHub 릴리스에서 OS별 파일 실행
- 장점
- 백그라운드 엔진(데몬)이 내장되어 별도 터미널 설정 불필요
- 모바일 연결
- 설정 → 내 호스트 → 기기 연결(Pair Device)에서 QR 스캔
서버 / CLI (★★☆)원격 개발 머신과 터미널 중심 환경
“npm install -g @getpaseo/cli”
- 설치 방법
- 전역 npm 설치 후 paseo 실행 (데이터 기본 경로 ~/.paseo)
- 원격 접속
- 암호화 릴레이 QR 또는 Tailscale/VPN/SSH 연결 지원
- 웹 UI
- paseo daemon config set features.webUi.enabled true로 브라우저 제공 가능
Docker / 자체 서버 (★★★)NAS·미니PC 상시 가동용
“ghcr.io/getpaseo/paseo:latest”
- 주의점
- 공식 이미지 안에 AI CLI가 없으므로 원하는 CLI를 이미지에 추가해야 함
- 필수 보안
- PASEO_PASSWORD 변경 + 외부 공개 시 반드시 HTTPS 리버스 프록시(Caddy/Nginx) 적용
- 접속 주소
- 먼저 서버 내부 http://localhost:6767 동작 확인 후 외부 개방
npm install -g @getpaseo/cli
paseo3. 꼭 알아야 할 세 단어: 프로젝트 · 워크스페이스 · 세션
Paseo 사이드바는 "채팅 목록"이 아니라 **"장소 목록"**입니다. 크기 순서 프로젝트 > 워크스페이스 > 세션을 학교에 비유하면 단번에 이해됩니다.
- 프로젝트 = 학교: Git 저장소나 폴더 하나를 "여기서 일할게요"라고 등록한 단위입니다. 폴더를 복사하지 않으므로 Paseo에서 프로젝트를 지워도 내 코드는 그대로 남습니다.
- 워크스페이스 = 교실(방): 실제 작업이 일어나는 공간(작업 폴더 1개)입니다. 채팅을 새로 시작해도 방은 유지되며, AI 없이 터미널·브라우저만 먼저 열어 둘 수도 있습니다.
- 세션 = 학생(탭): 워크스페이스 안에서 돌아가는 실행 단위 하나(AI 대화 탭, 터미널 탭, 브라우저 탭)입니다. 같은 방의 세션들은 같은 폴더(파일)는 공유하지만 대화 맥락은 서로 공유하지 않습니다.
| 자주 하는 오해 | 실제 동작 |
|---|---|
| 워크스페이스 하나 = 채팅 하나? | 아닙니다. 워크스페이스는 방이고, 한 방 안에 AI 대화·터미널·브라우저 세션이 여러 개 동시에 돌 수 있습니다. |
| 워크스페이스를 보관(archive)하면 코드가 삭제된다? | 로컬 방은 목록에서만 치워집니다. 단, 워크트리 방은 마지막 하나까지 보관할 때 워크트리 폴더가 정리되니 합치지 않은 변경을 먼저 확인하세요. |
| 세션을 새로 열면 앞 대화를 이어 받는다? | 같은 폴더를 볼 뿐 대화 맥락은 새로 시작합니다. 이어 가려면 기존 세션에 말하거나 요약을 붙여 넣으세요. |
4. 병렬 워크트리 실전과 paseo.json 설정
쇼핑몰 앱 my-app에서 ① 상품 정렬 기능(sort-products)과 ② 로그인 화면 다듬기(login-polish)를 동시에 진행한다고 가정해 봅시다.
- 1첫 번째 워크트리 방 만들기
New workspace → Isolation: New worktree → 시작 지점 origin/main → AI(예: Claude Code) 선택. 원본 main을 건드리지 않는 별도 폴더·브랜치가 생깁니다.
- 2무엇을 + 어떻게 확인할지 함께 지시
'상품 목록에 가격순·이름순 정렬을 추가하고 관련 테스트를 실행해 줘.'처럼 검증 기준까지 적어 주면 품질이 올라갑니다.
- 3두 번째 방을 만들어 다른 AI 동시 투입
사이드바에서 my-app을 다시 눌러 login-polish 방을 만들고 파일이 겹치지 않는 로그인 화면 작업을 맡깁니다(다른 AI 모델을 골라도 됩니다).
- 4포트 충돌 해결 — paseo.json 서비스 자동 배정
방 A가 3000번 포트를 쓰면 방 B는 충돌합니다. paseo.json에 type: service와 $PASEO_PORT를 정의하면 Paseo가 빈 포트를 자동 배정하고 web--sort-products--my-app.localhost:6767 같은 전용 주소를 만들어 줍니다.
{
"worktree": {
"setup": "npm ci",
"teardown": "rm -rf .cache || true"
},
"scripts": {
"test": { "command": "npm test" },
"web": {
"command": "npm run dev -- --port $PASEO_PORT",
"type": "service"
}
}
}5. 결과 검증 · 모바일 이어하기 · CLI 7대 명령
눈으로 검증하고 합치기
- Changes 탭: 초록(추가)·빨강(삭제) diff를 확인하고, 마음에 안 드는 부분은 *"정렬 상태를 URL에 남기지 말고 컴포넌트 안에만 두자"*처럼 한 줄로 수정 요청합니다.
- 리뷰 AI 붙이기: 같은 방에서
New agent로 다른 AI를 띄워 *"파일은 고치지 말고 변경분만 리뷰해 줘"*라고 맡깁니다. 단, 리뷰 AI의 "문제없습니다"도 의견일 뿐이므로 Terminal에서 직접npm test를 돌리고 내장 Browser 탭에서 화면을 확인한 뒤 커밋·PR·보관(archive)하세요. - 단축키:
Cmd+K(Windows/LinuxCtrl+K) Command Center로 기능을 바로 검색하고, 왼쪽 AI 대화·오른쪽 코드 스플릿 패널로 배치하면 편리합니다.
휴대폰·SSH로 밖에서 이어 하기
방은 집 컴퓨터 데몬(기본 포트 6767)에 하나만 있고, 데스크톱·휴대폰·CLI는 그 방을 들여다보는 창입니다.
- 모바일 릴레이: 데스크톱 설정 → 내 호스트 → 기기 연결 → Enable relay를 켜고 QR을 찍으면 포트 포워딩이나 VPN 없이 종단 간 암호화로 바로 연결됩니다. 지시를 보내고 앱을 닫아도 집 PC의 AI는 계속 일합니다.
- Tailscale / SSH: 릴레이가 막히면 양쪽에 Tailscale을 깔아
tailscale ip -4+ 포트6767로 직접 연결하거나, 이미 데몬이 켜진 원격 서버에ssh://user@host로 접속할 수 있습니다.
터미널이 무섭다면: CLI 핵심 명령어 빠른 복사
Paseo CLI 핵심 7대 명령
서비스 · 프로바이더 · 원격 SSH
6. AI에게 AI를 시키기 (오케스트레이션 · 스킬 · 플러그인)
AI가 다른 AI(Subagent)를 부르게 하기
- 설정 → 내 호스트 → Agents → Enable Paseo tools를 켭니다(기본값 꺼짐).
- 이미 떠 있던 세션에는 도구가 주입되지 않으므로 새 세션을 엽니다.
- 메인 AI에게 *"Paseo로 두 번째 AI를 띄워서 이 브랜치를 파일 수정 없이 리뷰하게 해 줘"*라고 지시하면, 입력창 근처
Subagents영역에 일꾼이 나타나 같은 폴더를 보며 독립적으로 일합니다. - 모델·사고 수준·모드를 에이전트 프로필로 저장해 두면 메인 AI가 상황에 맞는 프로필을 스스로 고르며, 스케줄·하트비트 자동 실행도 가능합니다.
Paseo 기본 오케스트레이션 스킬 4종
매번 길게 위임 문장을 쓰기 귀찮다면 앱의 설정 → 내 호스트 → Agents → Orchestration skills 또는 npx skills add getpaseo/paseo로 4가지 기본 스킬을 설치하세요.
| 스킬 | 용도 |
|---|---|
/paseo | 에이전트·워크스페이스·스케줄·하트비트 사용법을 안내하는 기본 참고서 |
/paseo-handoff | 파일·진행 상황·결정 사항·완료 기준까지 브리핑해 다른 AI에게 작업 인수인계 |
/paseo-committee | 어려운 문제를 서로 다른 두 AI에게 독립 분석시키고 메인 AI가 종합 |
/paseo-advisor | 파일은 건드리지 않고 내 계획이나 diff에 대한 다른 AI의 의견만 수렴 |
7. 자주 막히는 곳 (증상별 문제 해결 탐색기)
문제가 생기면 항상 ① 데몬이 켜져 있나 → ② 맞는 데몬에 붙었나 → ③ 프록시·네트워크 순서로 확인하세요. 아래에서 증상을 검색해 해결책을 바로 찾을 수 있습니다.
- AI 목록이 비어 있어요· 설치 · AI 인식
Paseo는 AI를 직접 만들지 않습니다. 터미널에서 claude나 codex를 한 번 실행해 로그인을 마친 뒤 Paseo를 다시 여세요.
해결 핵심:CLI 직접 설치·로그인 후 재실행구간:설치 - 진단에 '명령을 찾을 수 없음'이 떠요· 설치 · AI 인식
CLI가 데몬 PATH 밖에 있는 경우입니다. 설정 → 호스트 → Providers → Diagnostic에서 경로를 확인해 agents.providers.<이름>.command에 절대 경로를 적으세요.
해결 핵심:config.json에 절대 경로 지정구간:설치 - 두 번째 방에서 '포트가 이미 사용 중' 오류· 병렬 · 포트 · .env
파일은 분리되지만 포트는 PC에 하나입니다. --port 3002를 직접 주거나 paseo.json에 type: service와 $PASEO_PORT를 정의해 자동 배정받으세요.
해결 핵심:$PASEO_PORT + type: service구간:병렬 - 새 워크트리 방에서 .env가 없어 서버가 안 떠요· 병렬 · 포트 · .env
git이 무시한 .env는 자동 복사되지 않습니다. 저장소 루트에 .worktreeinclude를 만들어 .env를 적고 커밋하세요(worktree-include 내장 플러그인 활성 필요).
해결 핵심:.worktreeinclude 커밋구간:병렬 - QR을 찍었는데 반응이 없어요· 모바일 · Tailscale · SSH
릴레이 기본값은 꺼짐입니다. 설정 → 내 호스트 → 기기 연결 → Enable relay를 켜고 QR을 다시 띄우세요(CLI: paseo daemon pair).
해결 핵심:Enable relay 켜기구간:원격 - Tailscale 시간 초과 또는 SSH 연결 거부· 모바일 · Tailscale · SSH
양쪽 Tailscale 활성 및 데몬 IP를 확인하세요. SSH는 데몬을 대신 켜 주지 않으므로 원격 서버에서 ssh user@host 접속과 paseo daemon start를 먼저 확인하세요.
해결 핵심:tailscale ip -4 / paseo daemon start구간:원격 - 웹 UI가 하얗거나 404 / 페이지가 떠도 연결 안 됨· 서버 웹 UI · 프록시 · 플러그인
features.webUi.enabled를 켜고 데몬을 재시작하세요. 프록시에서는 Upgrade/Connection 헤더·Host 보존·proxy_buffering off·긴 타임아웃(3600s)을 켜야 합니다(Caddy는 기본 지원).
해결 핵심:webUi.enabled + WebSocket 헤더구간:서버 - 403 Invalid Host header 또는 HTTPS 혼합 콘텐츠 차단· 서버 웹 UI · 프록시 · 플러그인
DNS 리바인딩 방어 때문에 daemon.hostnames에 도메인을 추가해야 합니다. HTTPS 환경에서는 X-Forwarded-Proto: https 전달과 daemon.trustedProxies를 설정하세요.
해결 핵심:daemon.hostnames / X-Forwarded-Proto구간:서버 - 설정이 반영 안 되거나 플러그인이 안 보여요· 서버 웹 UI · 프록시 · 플러그인
daemon.listen 변경은 데몬 재시작이 필요합니다. 플러그인은 Enable plugins 마스터 스위치, running 상태, 호스트 일치 여부를 보고 paseo plugin logs로 오류를 확인하세요.
해결 핵심:paseo reload / plugin logs구간:설정
8. 자주 묻는 질문 (FAQ)과 용어 사전
Q1. Paseo를 설치하면 Claude나 Codex 요금제가 포함되나요?
Q2. 기존에 쓰던 /grill-me 같은 스킬이 Paseo 설정 카드에 안 보여요.
Q3. paseo.json을 만들었는데 새 방에서 setup이 안 돌아가요.
Q4. 집 서버(Docker/NAS)로 열 때 가장 중요한 보안 수칙은 무엇인가요?
Q5. Paseo 플러그인은 샌드박스로 격리되어 있나요?
핵심 용어 사전
| 용어 | 쉬운 설명 |
|---|---|
| 에이전트 (Agent) | 파일을 직접 수정하고 명령을 실행하는 AI 코딩 도구 |
| 프로바이더 (Provider) | Paseo와 각 AI CLI 사이의 실행·출력 연결 규칙 |
| 데몬 (Daemon) | 뒤에서 계속 돌아가는 엔진(기본 포트 6767). 앱·모바일·CLI가 모두 여기에 접속 |
| 워크트리 (Worktree) | 같은 Git 저장소에서 폴더와 브랜치를 독립적으로 떼어 내는 기능 |
| ACP / MCP | ACP는 AI 도구 간 공통 대화 규격, MCP는 AI에게 외부 도구(다른 AI 호출 등)를 연결하는 규격 |
| 오케스트레이션 | 여러 AI에게 일을 나누어 지휘하고 결과를 취합하는 작업 방식 |
Hafuture JSON 포맷터로 paseo.json · config.json 문법 검증하기
워크트리 자동화와 서비스 포트 배정에 쓰이는 paseo.json과 데몬 config.json을 브라우저에서 100% 로컬로 포맷·검증해 보세요.