hafuture

Paseo 사용설명서: 여러 AI 코딩 에이전트를 한 번에 굴리는 작업실 앱

Claude Code·Codex·OpenCode 등 여러 AI 코딩 에이전트를 Git 워크트리로 병렬 실행하고 모바일·CLI·서버에서 제어하는 Paseo(paseo.sh) 완벽 가이드. 설치, paseo.json, 스킬·오케스트레이션, 문제 해결까지 정리했습니다.

PaseoAI Coding AgentsClaude CodeCodexGit WorktreeOrchestrationDeveloper Tools

목차


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. 설치하기 — 세 가지 방법

내 환경에 맞는 Paseo 설치 방식 고르기
데스크톱 앱 (★☆☆)

처음이라면 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 동작 확인 후 외부 개방
bash
npm install -g @getpaseo/cli
paseo
실행 시 데몬이 켜지며 암호화 릴레이(QR 페어링) 사용 여부를 묻습니다. 설정은 PASEO_HOME(기본 ~/.paseo)에 저장됩니다.

3. 꼭 알아야 할 세 단어: 프로젝트 · 워크스페이스 · 세션

Paseo 사이드바는 "채팅 목록"이 아니라 **"장소 목록"**입니다. 크기 순서 프로젝트 > 워크스페이스 > 세션을 학교에 비유하면 단번에 이해됩니다.

  • 프로젝트 = 학교: Git 저장소나 폴더 하나를 "여기서 일할게요"라고 등록한 단위입니다. 폴더를 복사하지 않으므로 Paseo에서 프로젝트를 지워도 내 코드는 그대로 남습니다.
  • 워크스페이스 = 교실(방): 실제 작업이 일어나는 공간(작업 폴더 1개)입니다. 채팅을 새로 시작해도 방은 유지되며, AI 없이 터미널·브라우저만 먼저 열어 둘 수도 있습니다.
  • 세션 = 학생(탭): 워크스페이스 안에서 돌아가는 실행 단위 하나(AI 대화 탭, 터미널 탭, 브라우저 탭)입니다. 같은 방의 세션들은 같은 폴더(파일)는 공유하지만 대화 맥락은 서로 공유하지 않습니다.
자주 하는 오해실제 동작
워크스페이스 하나 = 채팅 하나?아닙니다. 워크스페이스는 방이고, 한 방 안에 AI 대화·터미널·브라우저 세션이 여러 개 동시에 돌 수 있습니다.
워크스페이스를 보관(archive)하면 코드가 삭제된다?로컬 방은 목록에서만 치워집니다. 단, 워크트리 방은 마지막 하나까지 보관할 때 워크트리 폴더가 정리되니 합치지 않은 변경을 먼저 확인하세요.
세션을 새로 열면 앞 대화를 이어 받는다?같은 폴더를 볼 뿐 대화 맥락은 새로 시작합니다. 이어 가려면 기존 세션에 말하거나 요약을 붙여 넣으세요.

4. 병렬 워크트리 실전과 paseo.json 설정

쇼핑몰 앱 my-app에서 ① 상품 정렬 기능(sort-products)과 ② 로그인 화면 다듬기(login-polish)를 동시에 진행한다고 가정해 봅시다.

  1. 1
    첫 번째 워크트리 방 만들기

    New workspace → Isolation: New worktree → 시작 지점 origin/main → AI(예: Claude Code) 선택. 원본 main을 건드리지 않는 별도 폴더·브랜치가 생깁니다.

  2. 2
    무엇을 + 어떻게 확인할지 함께 지시

    '상품 목록에 가격순·이름순 정렬을 추가하고 관련 테스트를 실행해 줘.'처럼 검증 기준까지 적어 주면 품질이 올라갑니다.

  3. 3
    두 번째 방을 만들어 다른 AI 동시 투입

    사이드바에서 my-app을 다시 눌러 login-polish 방을 만들고 파일이 겹치지 않는 로그인 화면 작업을 맡깁니다(다른 AI 모델을 골라도 됩니다).

  4. 4
    포트 충돌 해결 — paseo.json 서비스 자동 배정

    방 A가 3000번 포트를 쓰면 방 B는 충돌합니다. paseo.json에 type: service와 $PASEO_PORT를 정의하면 Paseo가 빈 포트를 자동 배정하고 web--sort-products--my-app.localhost:6767 같은 전용 주소를 만들어 줍니다.

json
{
  "worktree": {
    "setup": "npm ci",
    "teardown": "rm -rf .cache || true"
  },
  "scripts": {
    "test": { "command": "npm test" },
    "web": {
      "command": "npm run dev -- --port $PASEO_PORT",
      "type": "service"
    }
  }
}
Paseo는 base 브랜치(origin/main)에 커밋된 paseo.json을 읽습니다. port를 생략하고 $PASEO_PORT를 써야 방마다 충돌 없이 자동 배정됩니다.

5. 결과 검증 · 모바일 이어하기 · CLI 7대 명령

눈으로 검증하고 합치기

  • Changes 탭: 초록(추가)·빨강(삭제) diff를 확인하고, 마음에 안 드는 부분은 *"정렬 상태를 URL에 남기지 말고 컴포넌트 안에만 두자"*처럼 한 줄로 수정 요청합니다.
  • 리뷰 AI 붙이기: 같은 방에서 New agent로 다른 AI를 띄워 *"파일은 고치지 말고 변경분만 리뷰해 줘"*라고 맡깁니다. 단, 리뷰 AI의 "문제없습니다"도 의견일 뿐이므로 Terminal에서 직접 npm test를 돌리고 내장 Browser 탭에서 화면을 확인한 뒤 커밋·PR·보관(archive)하세요.
  • 단축키: Cmd+K(Windows/Linux Ctrl+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)를 부르게 하기

  1. 설정 → 내 호스트 → Agents → Enable Paseo tools를 켭니다(기본값 꺼짐).
  2. 이미 떠 있던 세션에는 도구가 주입되지 않으므로 새 세션을 엽니다.
  3. 메인 AI에게 *"Paseo로 두 번째 AI를 띄워서 이 브랜치를 파일 수정 없이 리뷰하게 해 줘"*라고 지시하면, 입력창 근처 Subagents 영역에 일꾼이 나타나 같은 폴더를 보며 독립적으로 일합니다.
  4. 모델·사고 수준·모드를 에이전트 프로필로 저장해 두면 메인 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. 자주 막히는 곳 (증상별 문제 해결 탐색기)

문제가 생기면 항상 ① 데몬이 켜져 있나 → ② 맞는 데몬에 붙었나 → ③ 프록시·네트워크 순서로 확인하세요. 아래에서 증상을 검색해 해결책을 바로 찾을 수 있습니다.

Paseo 증상별 문제 해결 사전9건
  • 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 요금제가 포함되나요?
아니요. Paseo는 이미 설치·로그인해 둔 AI 코딩 CLI를 한 화면에서 병렬 관리하는 작업실 앱입니다. 사용하는 AI 모델의 구독이나 API 요금은 기존과 동일하게 적용됩니다.
Q2. 기존에 쓰던 /grill-me 같은 스킬이 Paseo 설정 카드에 안 보여요.
정상입니다. 설정 → Agents → Orchestration skills 카드는 Paseo가 배포하는 /paseo 계열 4종만 관리합니다. 기존 Claude Code 스킬은 방을 만들 때 프로바이더를 Claude Code로 선택하면 CLI 본체가 ~/.claude/skills/에서 그대로 읽어 실행합니다.
Q3. paseo.json을 만들었는데 새 방에서 setup이 안 돌아가요.
90%는 커밋을 안 한 경우입니다. Paseo는 내가 선택한 base 브랜치(보통 origin/main)에 커밋된 paseo.json과 .worktreeinclude만 읽습니다.
Q4. 집 서버(Docker/NAS)로 열 때 가장 중요한 보안 수칙은 무엇인가요?
외부에 열기 전에 반드시 paseo daemon set-password(또는 PASEO_PASSWORD)로 비밀번호를 설정하고, 신뢰할 수 없는 네트워크에서는 Caddy·Nginx 등 HTTPS 리버스 프록시와 daemon.hostnames 허용 목록을 반드시 앞에 두세요.
Q5. Paseo 플러그인은 샌드박스로 격리되어 있나요?
아니요. 플러그인은 데몬 계정 권한과 앱 내부에서 직접 실행되는 격리되지 않은 코드입니다. 반드시 신뢰할 수 있는 출처의 플러그인만 설치하세요.

핵심 용어 사전

용어쉬운 설명
에이전트 (Agent)파일을 직접 수정하고 명령을 실행하는 AI 코딩 도구
프로바이더 (Provider)Paseo와 각 AI CLI 사이의 실행·출력 연결 규칙
데몬 (Daemon)뒤에서 계속 돌아가는 엔진(기본 포트 6767). 앱·모바일·CLI가 모두 여기에 접속
워크트리 (Worktree)같은 Git 저장소에서 폴더와 브랜치를 독립적으로 떼어 내는 기능
ACP / MCPACP는 AI 도구 간 공통 대화 규격, MCP는 AI에게 외부 도구(다른 AI 호출 등)를 연결하는 규격
오케스트레이션여러 AI에게 일을 나누어 지휘하고 결과를 취합하는 작업 방식

Hafuture JSON 포맷터로 paseo.json · config.json 문법 검증하기

워크트리 자동화와 서비스 포트 배정에 쓰이는 paseo.json과 데몬 config.json을 브라우저에서 100% 로컬로 포맷·검증해 보세요.

JSON 포맷터 열기