Paseo란? 휴대폰에서 Claude Code와 Codex를 함께 쓰는 방법

안녕하세요. 자바파커입니다.

요즘 개발 환경에는 AI 코딩 도구가 하나씩 늘어나고 있습니다. 복잡한 설계는 Claude Code에 물어보고, 구현은 Codex에 맡기고, 다른 작업은 Cursor나 OpenCode에서 처리하기도 합니다.

문제는 도구가 늘어날수록 작업 창도 늘어난다는 점입니다. 에이전트마다 터미널과 세션이 따로 있고, 여러 작업을 동시에 실행하면 어느 에이전트가 어떤 브랜치를 수정하는지 따라가기도 쉽지 않습니다. 잠깐 자리를 비운 동안 작업이 멈췄는지 확인하려면 다시 컴퓨터 앞에 앉아야 하고요.

Paseo는 이 문제를 해결하려는 오픈소스 코딩 에이전트 오케스트레이션 도구입니다.

결론부터 말하면 Paseo는 새로운 AI 모델이나 코딩 에이전트가 아닙니다. 이미 사용 중인 Claude Code, Codex, Cursor 같은 에이전트를 내 컴퓨터에서 실행하고, 데스크톱·웹·휴대폰·CLI라는 하나의 인터페이스에서 관리하는 제어판에 가깝습니다.

Paseo는 무엇인가

Paseo는 로컬 컴퓨터나 개발 서버에서 AI 코딩 에이전트를 실행하고 관리하는 오픈소스 애플리케이션입니다. 공식 저장소는 AGPL-3.0 라이선스로 공개되어 있습니다.

2026년 8월 공식 지원 페이지 기준으로 39개의 코딩 에이전트를 지원하며, 대표적으로 다음 도구를 연결할 수 있습니다.

• Claude Code
• OpenAI Codex
• Cursor
• GitHub Copilot
• OpenCode
• Gemini CLI
• Cline
• Kilo Code
• Qwen Code
• Kimi Code CLI

여기서 중요한 점이 하나 있습니다.

Paseo가 Claude Code나 Codex 사용 권한을 대신 제공하는 것은 아닙니다.

사용하려는 에이전트의 CLI를 먼저 설치하고 각 서비스에 인증해야 합니다. Paseo는 기존 CLI와 계정, 설정, MCP 서버, 스킬을 그대로 사용해 프로세스와 세션을 관리합니다. 따라서 Paseo를 설치했다고 유료 모델을 무료로 사용할 수 있는 것은 아닙니다.

이 구조 덕분에 코드는 Paseo의 클라우드 작업 공간이 아니라 내 컴퓨터 또는 내가 운영하는 서버에서 처리됩니다.

Paseo에서는 중앙의 로컬 daemon이 클라이언트와 코딩 에이전트 사이의 세션과 프로세스를 관리합니다.

왜 Paseo가 필요한가

1. 여러 에이전트를 한곳에서 관리한다

Paseo의 가장 눈에 띄는 기능은 멀티 프로바이더 지원입니다.

한 프로젝트에서 Claude Code 세션과 Codex 세션을 함께 열고, 각 에이전트의 진행 상황을 같은 화면에서 볼 수 있습니다. 하나의 모델에 모든 일을 맡기기보다 작업 특성에 맞춰 도구를 나눠 쓰는 개발자에게 유용한 구조입니다.

예를 들면 이런 흐름을 만들 수 있습니다.

1. Claude Code에 요구사항 분석과 구현 계획을 맡깁니다.
2. Codex가 별도 워크트리에서 기능을 구현합니다.
3. 다른 에이전트가 변경 사항과 테스트 결과를 검토합니다.
4. 개발자는 휴대폰에서 진행 상황과 diff를 확인합니다.

Paseo의 오케스트레이션 기능을 활성화하면 한 에이전트가 다른 프로바이더의 에이전트를 실행하는 구성도 가능합니다. 같은 제품 안에서만 동작하는 기본 서브에이전트와 달리, Claude Code가 Codex에 작업을 넘기는 식의 교차 프로바이더 위임을 만들 수 있다는 점이 특징입니다.

2. 휴대폰에서 작업을 시작하고 이어간다

Paseo daemon은 개발 머신에서 계속 실행되고, 휴대폰 앱은 그 daemon에 연결됩니다. 따라서 이동 중에도 새 작업을 지시하거나 진행 중인 대화를 확인하고 후속 요청을 보낼 수 있습니다.

예를 들어 외출 전에 테스트를 실행해 두고, 휴대폰에서 실패 로그를 확인한 뒤 다음과 같이 지시할 수 있습니다.

실패한 테스트의 원인을 확인하고 수정해 주세요.
기존 API 시그니처는 변경하지 말고, 수정 후 관련 테스트만 다시 실행하세요.

다만 이것은 코딩 에이전트가 휴대폰에서 실행된다는 뜻이 아닙니다. 실제 작업은 계속 개발 머신에서 일어납니다. 컴퓨터가 꺼지거나 daemon이 중지되면 휴대폰에서도 작업을 진행할 수 없습니다.

3. Git worktree로 병렬 작업을 격리한다

여러 에이전트가 같은 저장소를 동시에 수정하면 충돌이 발생하기 쉽습니다. Paseo는 Git worktree 기반 워크스페이스를 만들어 에이전트마다 별도 디렉터리와 브랜치를 사용할 수 있게 합니다.

main 저장소
├── feature-auth 워크트리   → Codex
├── fix-payment 워크트리    → Claude Code
└── update-docs 워크트리    → Gemini CLI

각 에이전트가 같은 파일을 직접 덮어쓰지 않으므로 병렬 작업을 비교적 안전하게 분리할 수 있습니다. 작업이 끝나면 기준 브랜치와 diff를 검토한 뒤 병합하거나 워크스페이스를 보관 처리할 수 있습니다.

각 에이전트는 격리된 worktree에서 작업하고, 변경 사항은 검토 단계를 거쳐 기준 브랜치에 병합합니다.

저장소 루트에 paseo.json을 두면 워크트리를 만든 직후 실행할 설치 명령과 테스트·개발 서버 같은 스크립트도 정의할 수 있습니다.

{
  "worktree": {
    "setup": "npm ci"
  },
  "scripts": {
    "test": { "command": "npm test" },
    "lint": { "command": "npm run lint" },
    "web": {
      "command": "npm run dev -- --port $PASEO_PORT",
      "type": "service"
    }
  }
}

워크트리를 생성할 때마다 의존성을 설치하고, 앱에서 테스트나 개발 서버를 실행하는 흐름을 표준화할 수 있는 셈입니다.

4. 음성, 스케줄, 반복 작업으로 확장할 수 있다

Paseo는 텍스트 채팅 외에 음성 입력을 지원합니다. 키보드 앞에 앉아 있지 않아도 문제를 설명하거나 다음 작업을 지시할 수 있습니다.

또한 일정에 따라 독립 작업을 시작하는 스케줄과, 같은 세션을 주기적으로 다시 깨우는 heartbeat 기능을 제공합니다. CI가 통과할 때까지 일정 간격으로 상태를 확인하거나, 장시간 실행되는 리팩터링을 계속 점검하는 용도로 활용할 수 있습니다.

자동화 수준이 높아질수록 편리하지만, 에이전트가 가진 파일·터미널·네트워크 권한도 함께 커진다는 점은 기억해야 합니다.

설치 방법

가장 쉬운 방법: 데스크톱 앱

처음 사용한다면 공식 다운로드 페이지에서 데스크톱 앱을 설치하는 방법이 가장 간단합니다.

1. Claude Code나 Codex 등 사용할 에이전트 CLI를 먼저 설치하고 로그인합니다.
2. Paseo 다운로드 페이지에서 운영체제에 맞는 앱을 설치합니다.
3. Paseo를 실행하고 프로젝트 폴더를 워크스페이스로 추가합니다.
4. 사용할 프로바이더와 모델을 선택해 첫 에이전트를 실행합니다.

데스크톱 앱에는 daemon이 포함되어 있어 별도 서버 설치 없이 자동으로 시작됩니다.

CLI로 실행하기

GUI가 없는 개발 서버나 원격 머신에서는 CLI를 설치할 수 있습니다.

npm install -g @getpaseo/cli
paseo

실행 중인 에이전트를 확인하고 후속 요청을 보내는 기본 명령은 다음과 같습니다.

paseo ls
paseo attach <agent-id>
paseo send <agent-id> "관련 테스트도 추가해 주세요"

에이전트를 실행할 때 프로바이더나 워크트리를 지정할 수도 있습니다.

paseo run --provider codex/<model-id> --worktree feature-auth \
  "로그인 기능을 구현하고 테스트를 실행해 주세요"

모델 ID와 세부 옵션은 버전에 따라 바뀔 수 있으므로 실제 사용 시에는 paseo --help와 공식 CLI 문서를 확인하는 편이 안전합니다.

휴대폰 연결하기

Paseo Desktop에서 Settings → Host → Pair a device로 이동해 Relay를 활성화한 뒤 QR 코드를 휴대폰 앱으로 스캔하면 됩니다.

공식 Relay는 포트 포워딩 없이 연결할 수 있고 트래픽에 종단 간 암호화를 적용합니다. Relay를 사용하지 않으려면 Tailscale 같은 VPN을 통해 daemon에 직접 연결하는 방식도 선택할 수 있습니다.

보안에서 꼭 확인할 점

Paseo는 로컬 우선 도구이지만, 설치만으로 모든 보안 문제가 해결되는 것은 아닙니다. 오히려 코딩 에이전트는 소스 코드와 셸, 로컬 자격 증명에 접근할 수 있으므로 일반 채팅 앱보다 더 조심해야 합니다.

daemon을 인증 없이 외부에 노출하지 않는다

기본적으로 daemon의 주소에 접근할 수 있는 클라이언트는 연결을 시도할 수 있습니다. localhost에서만 쓸 때는 접근 범위가 제한되지만, LAN 주소나 0.0.0.0에 바인딩하면 이야기가 달라집니다.

공식 보안 문서에서는 네트워크에 daemon을 공개할 때 비밀번호를 설정하고, 신뢰할 수 없는 네트워크에서는 Relay나 VPN을 사용하도록 권장합니다. 비밀번호 인증은 접근을 통제할 뿐 트래픽 자체를 암호화하지 않으므로, 인터넷에 포트만 직접 개방하는 방식은 피하는 편이 좋습니다.

QR 코드를 비밀번호처럼 다룬다

기기 연결에 사용하는 QR 코드나 페어링 링크를 획득한 사람은 daemon 연결을 시도할 수 있습니다. 화면 캡처를 공개 채널에 올리거나 장기간 보관하지 않는 것이 좋습니다.

에이전트의 권한은 Paseo보다 아래 계층에서 결정된다

Paseo는 프로바이더의 API 키를 대신 관리하지 않습니다. Claude Code, Codex 같은 CLI가 현재 사용자 권한과 기존 인증 정보를 사용해 실행됩니다.

따라서 중요한 것은 다음과 같습니다.

• 에이전트별 승인·샌드박스 설정 확인
• 운영 서버와 개발 환경 분리
• .env, SSH 키, 클라우드 자격 증명 접근 최소화
• Docker 사용 시 필요한 저장소만 마운트
• 중요한 변경은 자동 병합하지 않고 사람이 diff 검토

Paseo의 중앙 화면은 작업을 보기 쉽게 해주지만, 에이전트가 실행할 수 있는 명령을 자동으로 안전하게 바꿔주지는 않습니다.

장점과 한계

Paseo가 특히 잘 맞는 사람은 이미 둘 이상의 코딩 에이전트를 사용하고, 여러 저장소나 브랜치의 작업을 동시에 관리하는 개발자입니다. 홈 서버나 항상 켜진 개발 머신이 있고, 이동 중에도 에이전트 상태를 확인하고 싶다면 장점이 더 커집니다.

반대로 AI 코딩 도구 하나를 가끔 사용하는 정도라면 기존 터미널이나 공식 앱만으로도 충분할 수 있습니다. Paseo 자체를 관리하고 보안을 설정하는 비용이 추가되기 때문입니다.

Paseo를 처음 쓸 때 추천하는 흐름

처음부터 여러 에이전트와 자동 스케줄을 한꺼번에 켜기보다 작은 범위부터 확인하는 것이 좋습니다.

1. 개인 테스트 저장소 하나를 등록합니다.
2. 이미 익숙한 에이전트 하나만 연결합니다.
3. 작은 문서 수정이나 테스트 추가 작업을 맡깁니다.
4. worktree 격리와 diff 검토 흐름을 확인합니다.
5. Relay로 휴대폰을 연결하고 접근 권한을 점검합니다.
6. 익숙해진 뒤 두 번째 프로바이더와 오케스트레이션을 추가합니다.

특히 처음에는 자동 병합이나 장시간 반복 작업보다 실행 → 확인 → 후속 지시 → diff 검토 흐름에 익숙해지는 편이 안전합니다.

정리

Paseo는 Claude Code나 Codex를 대체하는 도구가 아닙니다. 여러 코딩 에이전트를 내 개발 환경에서 실행하고, 하나의 화면과 휴대폰에서 관리하기 위한 오픈소스 관제·오케스트레이션 계층입니다.

핵심은 네 가지로 정리할 수 있습니다.

• 여러 프로바이더의 코딩 에이전트를 한곳에서 실행하고 관리합니다.
• 데스크톱에서 시작한 작업을 휴대폰과 웹, CLI에서 이어갈 수 있습니다.
• Git worktree로 병렬 작업 공간을 분리할 수 있습니다.
• 에이전트 간 위임, 스케줄, heartbeat로 자동화 범위를 넓힐 수 있습니다.

AI 코딩 도구가 하나일 때는 좋은 프롬프트가 중요했습니다. 에이전트가 여러 개로 늘어나면 누가 어느 작업 공간에서 무엇을 하고 있는지 관리하는 구조가 더 중요해집니다.

Paseo는 바로 그 지점을 노리는 도구입니다. 여러 코딩 에이전트를 이미 번갈아 쓰고 있다면 한 번 테스트해볼 만합니다. 다만 편리한 원격 제어 기능만큼 접근 권한과 네트워크 보안도 함께 설계해야 합니다.

참고자료

• Paseo 공식 사이트
• Paseo 공식 문서
• Paseo GitHub 저장소
• 지원 코딩 에이전트 목록
• Git worktree 사용법
• Paseo 오케스트레이션
• 연결 및 페어링 가이드
• Paseo 보안 가이드