설치와 첫 실행
Paseo를 쓰기 시작하는 데 필요한 일은 세 가지입니다. 에이전트 프로그램을 하나 설치해 로그인해 두고, Paseo를 설치하고, 열어서 에이전트를 연결하는 것입니다. 이 장에서는 그 순서를 따라가고, 이어서 업데이트를 받는 방식과 처음에 자주 막히는 지점을 푸는 법까지 다룹니다.
준비물 — 꼭 하나, 있으면 좋은 것 하나
공식 문서는 이렇게 말합니다. “Paseo는 다른 에이전트를 관리할 뿐, 에이전트를 함께 싣고 오지 않는다.” 그래서 Paseo가 쓸모 있으려면 먼저 프로바이더(Paseo가 실행해 주는 에이전트 프로그램 한 종류 — Claude Code, Codex 등)의 CLI(글자로 명령을 입력해 쓰는 프로그램)를 하나 이상 내가 직접 설치하고, 내 로그인 정보로 실제로 작동하는지 확인해 두어야 합니다.
| 준비물 | 왜 필요한가 | 갖췄는지 확인하는 법 |
|---|---|---|
| 에이전트 CLI 하나 이상 | Paseo가 실행할 대상입니다. 이것이 없으면 Paseo가 맡길 에이전트가 없습니다. | 그 프로그램이 내 로그인 정보로 실제로 작동하는지 봅니다. 가장 흔한 두 가지(Claude Code, Codex)는 아래에서, 전체 목록은 3장에서 다룹니다. |
| GitHub CLI ( gh) | GitHub(코드를 올려 두고 함께 작업하는 웹 서비스)를 터미널에서 다루는 공식 명령 도구입니다. Paseo는 GitHub의 PR(내 변경을 원본에 합쳐 달라는 요청)을 워크스페이스(일 하나를 하는 자리. 작업 폴더가 딸려 있음)로 여는 기능과 일부 오케스트레이션(에이전트가 다른 에이전트에게 일을 나눠 맡기는 것) 기능에 이 도구를 씁니다. 처음에는 없어도 시작할 수 있습니다. | 설치한 뒤 로그인(인증)까지 해 둡니다. 공식 문서는 이것을 “있으면 좋은 것”으로 권합니다. |
설치 방법 세 가지
Paseo를 설치하는 길은 세 가지입니다. 어느 길이든 결국 하는 일은 같습니다. 데몬(컴퓨터에서 계속 켜져 있으면서 에이전트와 작업을 맡아 돌리는 Paseo의 본체 프로그램)을 켜는 것입니다. 차이는 데몬을 어디에, 어떤 모양으로 켜느냐입니다. 공식 문서가 권하는 것은 첫 번째, 데스크톱 앱입니다.
| 방법 | 이런 경우에 | 설치 | 자세히 |
|---|---|---|---|
| 데스크톱 앱 권장 | 내 컴퓨터에서 바로 쓰려는 대부분의 경우 | 내려받아서 엽니다. 데몬이 앱 안에 들어 있어 따로 설치할 것이 없습니다. | 데스크톱 앱 첫 실행 |
| 서버 / CLI | 모니터 없이 돌리는 컴퓨터, 개발용 서버, 또는 데스크톱 화면 없이 데몬만 켜 두고 싶은 경우 | 터미널에서 명령 두 줄 | 화면 없이 시작하기 |
| Docker | 서버, 개발용 서버, NAS, 홈랩처럼 프로그램을 Docker(프로그램을 격리된 상자(컨테이너)에 담아 돌리는 도구)로 돌리는 곳 | 공식 이미지를 실행 | Docker로 시작하기 |
데스크톱 앱 첫 실행
데스크톱 앱은 설치 과정이라 할 것이 거의 없습니다. 공식 문서의 표현 그대로 “열면 끝”입니다. 아래 단계를 차례로 넘겨 보세요.
1단계 — 내려받기. paseo.sh/download 또는 GitHub의 릴리스 페이지(github.com/getpaseo/paseo/releases)에서 내 컴퓨터에 맞는 설치 파일을 받습니다.
2단계 — 열기. 처음 열면 잠깐 시작 화면이 보입니다. 앱이 자기 안에 들어 있는 데몬을 스스로 켜기 때문입니다. 데몬을 따로 설치하거나 직접 켤 필요가 없습니다.
3단계 — 휴대폰 연결(원할 때). 휴대폰에서도 이어서 보고 싶다면 Settings → your host → Pair Device(설정 → 내 호스트 → 기기 짝짓기)로 들어가 연결합니다. 공식 문서의 연결 쪽에는 같은 메뉴가 Pair a device로 적혀 있습니다 — 같은 메뉴입니다. 여기서 호스트(데몬이 돌아가는 컴퓨터 — 지금은 이 컴퓨터)는 방금 앱을 연 내 컴퓨터입니다. 연결 방식과 보안은 7장에서 다룹니다.
앱이 열렸다면 설치는 끝났습니다. 이제 에이전트를 연결하고(아래), 일할 자리인 워크스페이스를 만들면(2장) 첫 일을 맡길 수 있습니다.
공식 문서가 안내하는 “다음에 읽을 것”과 이 가이드의 대응
| 공식 문서의 안내 | 이 가이드에서 |
|---|---|
| 여러 일을 동시에 — 워크트리를 따로 쓰고, diff를 검토하고, 데스크톱 앱에서 시험하기 | 2장 |
| 프로젝트 · 워크스페이스 · 세션이라는 작업 모델 | 2장 |
| 프로바이더가 무엇이고 Paseo가 이미 설치된 에이전트 프로그램을 어떻게 불러 쓰는지 | 3장 |
| 오케스트레이션 — 한 에이전트가 다른 프로바이더·모델에게 일을 넘기기 | 4장 |
| 연결 — 릴레이나 Tailscale로 접속하기 / Docker / 웹 화면을 내 데몬에서 직접 제공하기 | 7장 |
| CLI 명령 전체 | 8장 |
| 플러그인 — 믿을 수 있는 플러그인으로 새 화면·사이드바 버튼·데몬 기능·입력창 첨부 메뉴를 더하기 | 10장 |
| GitHub 저장소 · 문제 신고 | github.com/getpaseo/paseo · github.com/getpaseo/paseo/issues |
Claude Code · Codex 연결하기
가장 널리 쓰는 에이전트 둘을 예로 듭니다. 원리는 둘 다 같습니다. Paseo를 돌리는 컴퓨터(데몬이 켜진 컴퓨터 — 휴대폰이 아닙니다)에 그 에이전트의 CLI(글자 명령으로 쓰는 프로그램)를 설치하고 로그인해 두면, Paseo는 에이전트를 시작할 때 그 설치본과 그 로그인을 그대로 씁니다. Paseo를 거친다고 요금이 더 붙지도 않습니다.
| Claude Code | Codex | |
|---|---|---|
| Paseo에서 쓰면 돈이 더 드나 | 아니요. 사용량은 평소 Claude 요금제 한도에서 그대로 셉니다. 별도의 Agent SDK 크레딧을 따로 마련할 필요가 없습니다. | 아니요. Paseo는 Codex에 요금을 더하지 않습니다. |
| 필요한 것 | Claude Code가 포함된 Claude 요금제 | ChatGPT 요금제(ChatGPT로 로그인) 또는 API 키(쓴 만큼 요금을 매기는 계정용 비밀 열쇠) — 이 경우 OpenAI Platform 계정으로 청구됩니다. |
| 한도 · 요금 | 요금제의 평소 사용 한도가 그대로 적용됩니다. | 요금제의 평소 Codex 한도, 그리고 OpenAI의 표준 API 요금이 그대로 적용됩니다. |
| Paseo가 실행하는 방식 | 공식 claude CLI를 Claude Agent SDK(Claude Code를 다른 프로그램에서 부르는 공식 연결 도구)로 실행 | 공식 codex CLI와 그 app-server 인터페이스(다른 프로그램이 Codex와 대화하도록 열어 둔 공식 창구)로 실행 |
- Claude Code CLI를 설치하고 로그인합니다.Paseo를 돌리는 컴퓨터에서 합니다.
- Paseo에서 Claude Code 에이전트를 시작합니다.Paseo가 이미 있는 그 설치본과 계정을 씁니다.
Claude 프로필을 여러 개 두거나, 다른 실행 파일·다른 회사의 접속 주소를 쓰는 방법은 3장에서 다룹니다. 공식 사이트에는 Paseo와 Claude Desktop을 기능별로 견준 비교 페이지도 있습니다.
- Codex CLI를 설치합니다.Paseo를 돌리는 컴퓨터에서 합니다.
- 로그인합니다 — 둘 중 하나.ChatGPT 계정으로 로그인하면 내 ChatGPT 요금제에 포함된 몫을 쓰고, API 키로 로그인하면 OpenAI Platform 계정으로 쓴 만큼 청구됩니다.
- 터미널에서
codex가 실제로 켜지는지 확인합니다.여기까지 되면 Paseo가 Codex 에이전트를 시작할 때 이 설치본과 로그인을 씁니다.
Paseo에 Codex가 보이지 않으면 아래 소절을 보세요. 여러 Codex 프로필이나 다른 실행 파일·접속 주소는 3장에서 다룹니다. 공식 사이트에는 Paseo와 Codex 앱을 견준 비교 페이지도 있습니다.
로그인이 만료됐을 때 (Claude Code). Claude Code CLI에서 다시 로그인한 다음, Paseo에서 새 Claude Code 세션(에이전트와의 대화 하나 — 앱에서는 탭 하나)을 시작하세요. 이미 돌고 있던 세션은 시작할 때의 로그인을 계속 들고 있기 때문에, CLI에서 다시 로그인해도 그 세션은 바뀌지 않습니다.
- Paseo에는 에이전트가 들어 있지 않습니다. 에이전트 CLI를 하나 이상 직접 설치해 로그인해 두고, GitHub CLI(
gh)도 갖춰 두면 좋습니다. - 설치는 데스크톱 앱이 권장입니다. 내려받아 열면 데몬까지 자동으로 켜집니다. 서버/CLI와 Docker는 화면 없는 컴퓨터에 데몬을 켜 두는 길입니다.
- Claude Code와 Codex 모두 Paseo에서 쓴다고 요금이 더 붙지 않습니다. 내 요금제와 내 로그인을 그대로 씁니다. 다시 로그인했다면 새 세션을 시작해야 반영됩니다.
- 업데이트는 Stable이 기본이고 36시간에 걸쳐 퍼집니다(Check를 누르면 바로). 먼저 받고 싶으면 Settings → About → Release channel에서 Beta로 바꿉니다.
- 에이전트가 Not installed로 보이면 “새로 연 터미널에서 그 명령이 되는가”부터 확인하고, 프로바이더의 Diagnostic을 봅니다. 설정 파일을 고친 뒤에는
paseo reload를 실행합니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 1장에 있습니다.
프로젝트 · 워크스페이스 · 워크트리
Paseo의 기본 단위는 대화 하나가 아니라 일 하나를 하는 자리, 곧 워크스페이스입니다. 이 장에서는 프로젝트·워크스페이스·세션이 어떻게 포개지는지, 일마다 파일을 어떻게 떼어 놓는지, 여러 일을 동시에 맡기고 검토해 고르는 순서, 그리고 파일을 떼어 놓는 방법인 git 워크트리를 Paseo가 어떻게 만들고 준비하고 치우는지를 설명합니다.
채팅이 아니라 워크스페이스 — 프로젝트 › 워크스페이스 › 세션
공식 문서의 첫 문장은 “Paseo는 채팅이 아니라 워크스페이스를 중심으로 짜여 있다”입니다. 워크스페이스(workspace)는 일 하나가 이뤄지는 자리입니다. 워크스페이스에는 작업 폴더가 하나 딸려 있고, 그 안에서 세션(워크스페이스 안에서 돌아가는 것 하나하나 — 에이전트와의 대화, 터미널 등)을 여러 개 동시에 돌릴 수 있습니다. 앱에서는 세션 하나가 탭 하나로 열립니다.
my-app·main·fix-login-flow·redesign-settings는 공식 문서의 예시입니다.- 프로젝트가 될 수 있는 것은 세 가지입니다 — git 저장소(코드의 변경 이력이 함께 기록되는 프로젝트 폴더), GitHub 프로젝트, 또는 Paseo 데몬(내 컴퓨터에서 계속 켜져 에이전트와 워크스페이스를 맡아 돌리는 Paseo의 본체 프로그램)이 돌아가는 컴퓨터의 아무 폴더.
- 워크스페이스는 저마다 따로 일하는 자리입니다. 원래 쓰던 폴더(main checkout)용으로 하나를 두고, 새 기능에 하나를 더 만들고, GitHub의 PR(내 브랜치의 변경을 원본에 합쳐 달라는 요청) 하나를 또 다른 워크스페이스로 열 수 있습니다.
- 프로젝트를 등록하고, 목록을 보고, 이름을 바꾸고, 지우는 일은 CLI(터미널에서 글자 명령으로 쓰는 프로그램)의 프로젝트 명령으로도 할 수 있습니다. → 8장
격리 방식 고르기 — Local과 Worktree
워크스페이스마다 격리 방식(Isolation)(이 워크스페이스가 파일을 다른 일과 함께 쓸지, 따로 떼어 쓸지 정하는 설정)이 하나씩 정해집니다. 고를 수 있는 것은 둘입니다.
tidy-fox·bold-owl은 공식 문서 예시에 나오는 워크트리 이름입니다.| Local | Worktree (앱 화면 표기: New worktree) | |
|---|---|---|
| 무엇을 하나 | 원래 쓰던 폴더처럼 이미 있는 폴더를 그대로 씁니다. | Paseo가 관리하는 git 워크트리를 새로 만들거나, 이미 있는 것을 엽니다. |
| 언제 고르나 | 세션들이 디스크에 이미 있는 파일을 함께 써야 할 때 | 그 일에 자기만의 폴더와 브랜치가 필요할 때 — 예를 들어 여러 에이전트를 동시에 돌릴 때 |
여기서 워크트리(worktree)는 같은 저장소를 다른 폴더·다른 브랜치(원본을 건드리지 않고 따로 작업하기 위한 이력의 갈래)로 하나 더 꺼내 놓은 작업 폴더입니다. git이 원래 가진 기능이고, Paseo는 이 폴더를 만들고 치우는 일을 대신 해 줍니다.
워크스페이스 만들기
워크스페이스는 앱에서도, CLI에서도 만들 수 있습니다. 앱에서는 New workspace(새 워크스페이스)를 열어 아래 순서로 고릅니다.
- 프로젝트를 고릅니다어느 코드 폴더의 일인지 정합니다.
- Isolation(격리)을 정합니다원래 폴더를 그대로 쓸지, New worktree로 새 폴더와 브랜치를 받을지 고릅니다. New worktree라면 어디서 갈라져 나올지, 곧 출발점도 고릅니다 — 예:
origin/main(서버에 있는 원본 줄기를 내 컴퓨터에서 가리키는 이름). - 에이전트와 모델을 고르고 할 일을 적어 보냅니다어떤 에이전트를 쓸 수 있는지는 3장에서 다룹니다.
에이전트 없이 먼저 만들어도 됩니다
에이전트를 바로 시작하지 않고 워크스페이스만 만들 수 있습니다. 작업 폴더는 준비되어 있으므로 터미널을 열거나, 프로그램을 띄우거나, 파일을 둘러보다가 나중에 에이전트를 시작하면 됩니다.
세션은 언제든 더 붙입니다
워크스페이스가 생긴 뒤에는 에이전트 옆에 터미널을 열고, 변경을 검토할 두 번째 에이전트를 시작하고, 띄운 프로그램을 확인할 브라우저 탭을 엽니다. 모두 같은 워크스페이스의 탭으로 들어갑니다.
“에이전트 만들기”와는 별개입니다
워크스페이스를 만드는 것과 에이전트를 만드는 것은 서로 다른 동작입니다. 이미 있는 워크스페이스에 에이전트를 넣고 싶으면 그 워크스페이스를 지정해서 시작합니다.
여러 일을 동시에 — 시작부터 합치기까지 네 단계
워크스페이스 모델은 서로 상관없는 일 여러 개를 에이전트 여러 개에게 한꺼번에 맡길 때 특히 쓸모가 있습니다. 일마다 워크스페이스를 하나씩 만들고 격리를 New worktree로 고르면, 일마다 자기 워크트리와 브랜치가 생기고 에이전트·파일·diff·터미널·브라우저 탭이 그 워크스페이스 안에 함께 모입니다.
준비물은 셋입니다 — 데스크톱 앱(1장), 내 컴퓨터에 있는 git 저장소, 설치하고 로그인해 둔 에이전트 하나 이상(3장). 아래 설명은 공식 문서처럼 저장소에 origin/main(서버에 있는 원본 줄기를 내 컴퓨터에서 가리키는 이름) 브랜치가 있다고 가정합니다.
1단계 — 두 작업 시작. New workspace에서 격리를 New worktree, 출발점을 origin/main으로 고르고 에이전트에게 첫 번째 일을 보냅니다. 같은 방법으로 워크스페이스를 하나 더 만들어 두 번째 일을 보냅니다. 두 에이전트는 동시에 일합니다. → 자세히
2단계 — 변경 검토. 워크스페이스를 골라 Changes(바뀐 곳)에서 diff를 읽습니다. 고칠 점은 그 워크스페이스의 에이전트에게 보내고, 다른 의견이 필요하면 같은 워크스페이스에 에이전트를 하나 더 불러 검토만 시킵니다. → 자세히
3단계 — 실행하고 시험. 그 워크스페이스에서 터미널을 열어 테스트(코드가 제대로 동작하는지 자동으로 확인하는 검사)나 개발 서버(만드는 중인 웹 앱을 내 컴퓨터에서 미리 띄워 보는 프로그램)를 돌리고, 웹 앱이면 브라우저 탭으로 직접 써 봅니다. 두 워크스페이스에서 같은 프로그램을 동시에 띄울 때는 포트 번호(프로그램마다 따로 쓰는 통신 창구 번호)가 겹치지 않게 합니다. → 자세히
4단계 — 합칠 것 고르기. 서로 독립된 일이면 브랜치마다 검토해 합치고, 같은 일을 두 가지로 만들어 본 것이면 남길 쪽을 고릅니다. 다 쓴 워크스페이스는 보관(archive)합니다. → 자세히
직접 따라 해 보려면 활용편 두 가지 일을 동시에와 검토하고 돌려 보기를 보세요.
- Paseo는 대화가 아니라 워크스페이스 중심입니다. 프로젝트 안에 워크스페이스가, 워크스페이스 안에 세션(에이전트 대화·터미널·브라우저·diff, 앱에서는 탭)이 들어 있습니다.
- 워크스페이스마다 격리 방식을 고릅니다. Local은 이미 있는 폴더를 그대로, Worktree(화면 표기 New worktree)는 일마다 새 폴더와 브랜치를 씁니다. 워크트리는 워크스페이스의 파일을 떼어 놓는 한 방법일 뿐, 워크스페이스와 같은 말이 아닙니다.
- 워크스페이스는 에이전트 없이도 만들 수 있고, 만든 뒤 세션을 얼마든지 더 붙일 수 있습니다.
- 여러 일을 동시에 할 때는 두 작업 시작 → 변경 검토 → 실행·시험 → 합칠 것 고르기 순서로 갑니다. 파일은 워크트리마다 따로지만 포트는 컴퓨터가 함께 쓰므로 겹치지 않게 합니다.
- 새 워크트리의 출발점은
main보다origin/main이 안전합니다. - git이 무시하는 내 설정 파일은
.worktreeinclude로 복사하고, 설치 같은 준비와 정리는paseo.json의 setup·teardown에 적습니다. Paseo는 고른 기준 브랜치에 커밋된paseo.json을 읽습니다. - 워크스페이스를 보관해도 워크트리 폴더는 그것을 쓰는 마지막 워크스페이스가 보관된 뒤에 지워집니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 2장에 있습니다.
에이전트 고르기 — 프로바이더와 프로필
Paseo 안에는 AI가 들어 있지 않습니다. 내가 설치하고 로그인해 둔 에이전트(사람 대신 코드를 읽고 고치고 명령을 실행하는 AI 프로그램)를 Paseo가 대신 실행해 줄 뿐입니다. 이 장에서는 그 연결 고리인 프로바이더가 무엇인지, 어떤 에이전트를 쓸 수 있는지, 목록에 없는 것은 어떻게 더하는지, 그리고 자주 쓰는 설정 조합을 프로필로 저장해 한 번에 고르는 방법을 설명합니다.
프로바이더란 — Paseo와 에이전트 사이의 약속
공식 문서는 프로바이더(provider)를 Paseo와 바깥의 에이전트 CLI(Command Line Interface — 글자 명령으로 쓰는 프로그램) 하나 사이의 약속이라고 정의합니다. 약속의 내용은 네 가지입니다. 그 에이전트를 어떻게 실행하는지, 에이전트가 내놓는 출력을 어떻게 실시간으로 받아 오는지, 내가 입력한 것을 어떻게 돌려보내는지, 그리고 어떤 모드(에이전트가 일하는 방식. 예: 명령을 실행하기 전에 허락을 묻는지)를 지원하는지입니다. 평소에는 “Paseo에 연결해 쓰는 에이전트 프로그램 한 종류”로 읽으면 됩니다.
중요한 점은 실제 에이전트 프로그램은 내 컴퓨터에 설치되어 있고, 평범한 프로그램으로 실행된다는 것입니다(원문 표현은 normal subprocess — 다른 프로그램이 시작시킨 보통의 프로그램). Paseo가 따로 감춰 둔 AI를 쓰는 것이 아닙니다.
이 구조 덕분에 달라지지 않는 것과 새로 얻는 것이 있습니다.
쓰던 것은 그대로
이미 설치하고 로그인해 둔 에이전트를 그대로 씁니다. 구독, 설정, 스킬(에이전트에게 미리 알려 둔 작업 요령 묶음), MCP 서버(에이전트에게 연결해 둔 도구들)가 모두 그대로 유지됩니다.
일마다 다른 에이전트
에이전트 여러 개를 동시에 돌리고, 일마다 어느 프로바이더에게 맡길지 고릅니다. 워크트리를 나눠 동시에 돌리는 방법은 2장에 있습니다.
검토는 한 앱에서
어느 에이전트가 한 일이든 같은 앱에서 살펴봅니다. 워크스페이스(일 하나를 하는 자리)에는 편집기, 터미널, diff(바뀌기 전과 후의 차이)가 있고, 데스크톱 앱에서는 브라우저도 있습니다.
두 갈래 — Native support와 ACP catalog
Paseo가 에이전트를 연결하는 길은 둘입니다. Native support(기본 지원)는 주요 에이전트마다 Paseo가 전용 어댑터(서로 다른 두 프로그램이 통하도록 사이에서 맞춰 주는 연결 부품)를 함께 넣어 둔 것이고, ACP catalog(ACP 카탈로그)는 ACP(Agent Client Protocol — 에이전트와 그것을 부리는 앱이 주고받는 공통 규칙)를 따르는 에이전트라면 무엇이든 공용 어댑터 하나로 연결하는 길입니다.
| Native support (기본 지원) | ACP catalog (ACP 카탈로그) | |
|---|---|---|
| 연결 방식 | 주요 에이전트마다 Paseo에 들어 있는 전용 어댑터 | ACP를 따르는 에이전트 모두를 맡는 공용 어댑터 |
| 대상 | Claude Code, Codex, OpenCode, Pi, Antigravity, Muse Code | Cursor, Gemini, GitHub Copilot, Hermes, Kimi, Qwen Code와 그 밖 25개 이상. 목록에 없는 ACP 에이전트도 직접 추가 가능 |
| 쓰기 시작 | 해당 CLI가 설치되어 있으면 Paseo가 자동으로 찾아냅니다 | Paseo가 골라 둔 카탈로그에서 한 번 클릭으로 설치합니다 |
| 함께 오는 것 | 모드 정보가 미리 들어 있고, 해당하는 에이전트는 음성 기능(8장)도 지원합니다 | 무엇을 할 수 있는지는 에이전트가 실행될 때 스스로 알려 줍니다 |
바로 쓸 수 있는 여섯 가지
Native support에 속한 여섯 가지는 해당 CLI를 설치하고 로그인해 두기만 하면 따로 손댈 것 없이 Paseo에서 바로 쓸 수 있습니다.
| 이름 | 어떤 에이전트인가 (공식 문서 소개) | 준비 |
|---|---|---|
| Claude Code | Anthropic의 코딩 에이전트. MCP 지원, 실시간 출력(streaming), 깊은 추론. | Claude Code CLI 설치·로그인 → 1장 |
| Codex | OpenAI의 코딩 에이전트(원문 표현 workspace agent). 샌드박스(프로그램이 건드릴 수 있는 범위를 가둬 두는 안전 울타리) 제어, 선택해서 켜는 네트워크 접근. | Codex CLI 설치·로그인 → 1장 |
| OpenCode | 오픈소스 코딩 도우미. 여러 회사의 AI 모델을 골라 쓸 수 있습니다. | OpenCode 설치·로그인 |
| Pi | 터미널에서 쓰는 단출한 코딩 에이전트. 여러 회사의 AI 모델을 지원합니다. | Pi 설치·로그인 |
| Antigravity | 내가 설치한 agy CLI를 Paseo에 내장된 프로바이더 플러그인으로 씁니다. | agy 설치 후 한 번 실행해 로그인 → 아래 절 |
| Muse Code | Meta의 터미널 코딩 에이전트. 프로바이더 플러그인 형태로 Paseo에 함께 들어 있습니다. | Muse Code 설치 후 muse login → 아래 절 |
에이전트 프로필 — 자주 쓰는 조합에 이름 붙이기
에이전트를 시작할 때는 고를 것이 여럿입니다. 어느 프로바이더를 쓸지, 어느 모델(에이전트의 두뇌 역할을 하는 AI)을 쓸지, 어떤 모드(일하는 방식. 예: 실행 전에 허락을 묻는지)로 돌릴지, 생각 깊이(thinking level)(답하기 전에 얼마나 깊이 따져 볼지)는 얼마로 할지, 그 밖에 켤 수 있는 기능은 무엇인지. 에이전트 프로필(agent profile)은 함께 쓰는 이 설정들을 이름 붙여 저장해 둔 것입니다. 에이전트를 만들 때 UI work(화면 작업), Planning(계획), Review(검토) 같은 이름만 고르면 됩니다.
프로필은 두 쪽에 쓸모가 있습니다.
나에게
한 번 고르면 저장해 둔 프로바이더, 모델, 모드, 생각 깊이, 기능 설정이 함께 적용됩니다. 매번 하나씩 고르지 않아도 됩니다.
일을 나눠 맡기는 에이전트에게
프로필에 적어 둔 메모가 “이 설정은 이런 일에 쓰라”는 안내가 됩니다. 다른 에이전트에게 일을 맡기는 에이전트가 이 메모를 읽고 설정을 고릅니다(아래 절).
프로필은 Settings → your host → Agents → Agent profiles(설정 → 내 호스트 → 에이전트 → 에이전트 프로필)에서 만듭니다. 순서는 바로 다음 절에 있고, 직접 따라 해 보려면 활용편 프로필 저장하고 검토 맡기기를 보세요.
- 프로바이더는 Paseo와 에이전트 CLI 하나 사이의 약속입니다(실행 방법, 출력 받기, 입력 보내기, 지원 모드). 에이전트 프로그램은 내 컴퓨터에 설치되어 평범하게 실행됩니다.
- 연결 길은 둘입니다. 전용 어댑터가 내장된 Native support 여섯 가지(Claude Code, Codex, OpenCode, Pi, Antigravity, Muse Code)와, 공통 규칙을 따르는 에이전트를 앱 안 카탈로그에서 더하는 ACP catalog입니다.
- 어느 쪽이든 설치와 로그인은 내가, 실행은 Paseo가 합니다. 구독·설정·스킬·MCP 서버는 그대로 유지됩니다.
- Antigravity는 허락을 묻지 않고 모든 명령을 실행하며 Paseo tools를 쓸 수 없습니다. Muse Code는 샌드박스를 끈 채로 시작하고, 1.4.1 기준으로 Paseo tools를 쓸 수 없습니다.
- 목록 밖의 일(다른 서비스 주소, 여러 계정, 실행 파일 교체, ACP 에이전트 추가, 끄기)은 설정 파일
~/.paseo/config.json에서 하고,paseo reload뒤 다음에 시작하는 에이전트부터 적용됩니다. - 에이전트 프로필은 프로바이더·모델·모드·생각 깊이·기능을 이름 하나로 묶은 것입니다. 모델 고르는 창에서 한 번에 적용하고, When to use 메모는 일을 나눠 맡기는 에이전트가 설정을 고를 때 읽습니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 3장에 있습니다.
에이전트가 에이전트를 부리기 — 오케스트레이션
지금까지는 내가 에이전트 하나하나에게 직접 일을 시켰습니다. 이 장에서는 한 걸음 더 나아가, 에이전트가 다른 에이전트를 만들어 일을 나눠 맡기고 결과를 모아 오게 하는 방법을 다룹니다. 설정 하나를 켜 두고 평소처럼 말로 부탁하면 됩니다.
오케스트레이션이란
오케스트레이션(orchestration)은 에이전트(사람 대신 코드를 읽고 고치고 명령을 실행하는 AI 프로그램)가 다른 에이전트를 만들어 일을 나눠 맡기고 결과를 모으는 것을 말합니다. 일을 받은 쪽을 이 가이드에서는 일꾼 에이전트(서브에이전트, subagent)라고 부릅니다. 공식 문서의 표현으로는, Paseo는 코딩 에이전트가 다른 에이전트들을 조율하고, 일을 여러 프로바이더(Paseo가 실행해 주는 에이전트 프로그램 한 종류 — Claude Code, Codex 등)와 여러 컴퓨터에 나누고, 작업이 자동으로 계속 굴러가게 해 줍니다.
왜 쓰나. 조사·구현·검토처럼 서로 떨어진 일을 여러 에이전트에게 나눠 동시에 진행할 수 있습니다. 또 만든 에이전트와 다른 프로바이더의 에이전트에게 검토를 맡기면 다른 모델의 판단을 얻을 수 있습니다. 메인 대화는 계획과 결정에만 쓰고, 손이 많이 가는 일은 일꾼에게 넘기는 식입니다.
Paseo tools 켜고 처음 맡겨 보기
Paseo tools는 Paseo 안에서 도는 에이전트가 자기 호스트(Paseo의 본체 프로그램인 데몬이 돌아가는 컴퓨터)의 에이전트와 워크스페이스(일 하나를 하는 자리 — 작업 폴더가 딸려 있음)를 직접 다루게 해 주는 내장 도구입니다. 공식 문서는 “Built-in Paseo tools (MCP)”라고 적는데, MCP는 에이전트에게 도구를 쥐여 주는 표준 방식의 이름입니다. 이 도구를 에이전트에게 넣어 주는 기능(tool injection, 도구 주입)은 기본으로 꺼져 있으므로 한 번 켜야 합니다.
1단계 — 설정 열기. Settings → your host → Agents(설정 → 내 호스트 → 에이전트)를 엽니다.
2단계 — 스위치 켜기. Enable Paseo tools(Paseo 도구 사용)를 켭니다. 처음에는 꺼져 있습니다.
3단계 — 에이전트를 새로 시작하거나 다시 불러오기. 처음에는 새 에이전트를 시작하는 쪽이 가장 쉽습니다. 새 에이전트를 시작하거나, 이미 있는 에이전트를 다시 불러옵니다(reload). 그래야 그 에이전트가 도구를 받습니다. 스위치를 켜기 전부터 돌던 대화는 그대로 두면 도구가 없습니다.
4단계 — 말로 부탁하기. 위처럼 “Paseo를 써서 …” 하고 부탁합니다. 브랜치(원본을 건드리지 않고 따로 작업하는 이력의 갈래) 검토처럼 파일을 고치지 않는 일로 시작하면 부담이 없습니다.
부탁을 보내면 일꾼 에이전트가 메시지 입력창 근처의 Subagents track(일꾼 에이전트가 줄지어 보이는 자리)에 나타납니다. 눌러서 열면 일꾼의 대화를 그대로 따라갈 수 있습니다. 일꾼이 끝나면 메인 에이전트가 알림을 받고, 일꾼이 일하는 동안에도 나는 메인 에이전트와 계속 이야기할 수 있습니다.
일꾼 에이전트는 어디에 보이나 — Subagents track
맡긴 일은 메시지 입력창(composer) 근처의 Subagents track(일꾼 에이전트 목록 자리)에서 확인합니다. 여기서 일꾼을 열어 무엇을 하고 있는지 들여다봅니다.
열면 온전한 대화 — 이어서 지시 · 설정 바꾸기 · 보관 · 떼어 내기
열면 읽기 전용 기록 — 지켜볼 수만 있음
이 자리에는 두 종류의 일꾼이 보입니다. Paseo가 만들어 준 Paseo 서브에이전트와, 에이전트 프로그램이 자기 안에서 스스로 만든 프로바이더 자체 서브에이전트(native provider subagent)입니다. 둘은 내가 할 수 있는 일이 다릅니다.
| Paseo 서브에이전트 | 프로바이더 자체 서브에이전트 | |
|---|---|---|
| 프로바이더 | 설정된 어떤 프로바이더든 | 일을 맡긴 에이전트 프로그램이 알아서 정함 |
| 워크스페이스 | 지금 워크스페이스, 또는 따로 지정한 워크스페이스 | 프로바이더가 알아서 관리 |
| 대화 | 내가 말을 걸 수 있는 온전한 에이전트 세션(워크스페이스 안에서 도는 대화 하나 — 앱에서는 탭) | 읽기 전용 기록(타임라인) |
| 내가 할 수 있는 것 | 이어서 지시하기, 설정 바꾸기, 보관(archive)(활성 목록에서 치워 두기), 떼어 내기(detach) | 시작부터 끝까지 프로바이더가 관리 |
Paseo 서브에이전트가 다른 워크스페이스에서 일하더라도 부모 에이전트(일을 맡긴 쪽 — 앞의 메인 에이전트)의 Subagents track에 그대로 속합니다. 동시에 자기 워크스페이스에는 탭으로도 열립니다. 일꾼을 부모에게서 떼어 독립된 최상위 에이전트로 만들고 싶으면 떼어 내기(detach)를 합니다 — 앱에서 하거나 CLI의 paseo agent detach로 합니다. 워크스페이스와 부모 관계가 정해지는 규칙은 어디서 일하나, 누구의 일인가에 있습니다.
만들게 한 뒤 다른 에이전트에게 검토시키기
변경을 만드는 에이전트와 그것을 평가하는 에이전트를 다르게 고르는 방법입니다. 자기가 쓴 글의 오탈자는 잘 안 보이는 것처럼, 만든 쪽이 아닌 다른 눈으로 다시 보게 하는 것입니다.
부탁에 나오는 말을 풀면 이렇습니다. 프로필은 자주 쓰는 에이전트 설정(어떤 프로바이더(에이전트 프로그램 한 종류)·모델·모드)을 이름 붙여 저장해 둔 것이고, 워크트리 격리는 이 일만을 위한 폴더와 브랜치를 새로 꺼내 쓴다는 뜻입니다. 다른 모델의 판단을 받고 싶다면 구현용과 검토용에 서로 다른 프로바이더의 프로필을 쓰세요. 프로필 만들기는 3장, 따라 하기는 활용편 실습 5에 있습니다.
- 오케스트레이션은 에이전트가 다른 에이전트(일꾼)를 만들어 일을 나눠 맡기고 결과를 모으는 것입니다. 나는 메인 에이전트에게 말로 부탁하면 됩니다.
- 시작하는 길은 둘입니다 — Settings → your host → Agents에서 Enable Paseo tools를 켜거나(기본 꺼짐, 켠 뒤 에이전트를 새로 시작하거나 다시 불러오기), 에이전트가
paseoCLI를 쓰게 합니다. - 맡긴 일은 입력창 근처 Subagents track에서 따라갑니다. Paseo 서브에이전트는 말을 걸고 떼어 낼 수 있고, 프로바이더 자체 서브에이전트는 읽기 전용입니다.
- 읽기만 하는 조사는 한 워크스페이스에서 나눠도 되지만, 고치는 일은 변경마다 워크트리를 따로 줍니다. 만든 뒤에는 다른 에이전트에게 새 대화로 검토시킵니다.
- 다른 컴퓨터의 에이전트는 CLI로 다룹니다. Paseo tools는 메인 에이전트가 있는 호스트 안에서만 동작합니다.
- 하트비트는 같은 에이전트를 다시 깨우고, 예약은 매번 새 에이전트를 시작합니다(5장).
- 스킬 네 가지(
/paseo·/paseo-handoff·/paseo-committee·/paseo-advisor)는 선택 사항이며, 긴 부탁을 한 줄로 줄여 줍니다. - 프로바이더별로 도구를 줄일 수 있지만, 그것은 보안 장치가 아닙니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 4장에 있습니다.
예약과 하트비트
내가 자리에 없어도 정해 둔 시간에 에이전트(사람 대신 코드를 읽고 고치고 명령을 실행하는 AI 프로그램)가 일하게 하는 방법은 두 가지입니다. 예약(schedule)은 시간이 될 때마다 새 에이전트를 시작하고, 하트비트(heartbeat)는 이미 일하고 있는 같은 에이전트를 일정한 간격으로 다시 깨웁니다. 이 장은 둘의 차이와, 만들고 관리하는 방법을 다룹니다.
예약과 하트비트, 무엇이 다른가
공식 문서의 정의는 이렇습니다. 예약은 cron(크론 — “몇 시 몇 분, 무슨 요일”처럼 되풀이되는 시각을 적는 표기법. 읽는 법은 아래) 주기에 맞춰 새 에이전트를 시작합니다. “이 시각에, 이 저장소(코드와 변경 이력이 담긴 프로젝트 폴더)에서, 이 에이전트 설정으로, 이 프롬프트(에이전트에게 보내는 부탁 글)를 실행해 줘”라는 약속입니다. 하트비트는 되풀이되는 프롬프트를 이미 있는 에이전트 하나에게 다시 보내, 그 에이전트가 상황을 다시 살피고 같은 대화를 이어 가게 합니다.
| 예약 (schedule) | 하트비트 (heartbeat) | |
|---|---|---|
| 누가 일하나 | 실행할 때마다 새 에이전트 | 이미 있는 에이전트 하나 |
| 앞의 일을 기억하나 | 아니요. 매번 깨끗한 상태로 시작합니다 | 네. 같은 대화를 이어 갑니다 |
| 맞는 일 | 매일 아침 정리, 정기 보고, 정기 점검 | 하던 일을 끝까지 밀고 가기 — 예: 하던 리팩터링(동작은 그대로 두고 코드 구조를 정리하는 일)을 20분마다 이어 가기 |
| 관리할 수 있는 것 | 자세히 보기 · 일시 정지 · 다시 시작 · 지금 한 번 실행 · 바꾸기 · 지우기 | 일부러 가볍게 — 만들기와 지우기가 중심 (자세히) |
두 기능은 속에서 같은 cron 엔진(정해진 시각이 되면 일을 시작시키는 부품)을 쓰지만, 사용자에게 보이는 기능으로는 따로 나뉘어 있습니다. 그래서 이 가이드에서도 “예약”이라고 하면 새 에이전트를 시작하는 쪽만, “하트비트”라고 하면 같은 에이전트를 깨우는 쪽만 가리킵니다.
만드는 네 가지 길
예약은 네 군데에서 만들 수 있습니다. 어디에서 만들든 담기는 내용은 같습니다 — 언제(cron 주기), 어디서(저장소), 어떤 에이전트로(에이전트 설정), 무엇을(프롬프트).
| 길 | 어떻게 | 이럴 때 |
|---|---|---|
| 앱에서 | Schedules(예약) 화면을 열고 에이전트 설정, cron 주기, 저장소, 프롬프트를 넣어 만듭니다. | 공식 문서가 꼽는 기본 방법. 만들기와 관리를 모두 여기서 합니다. |
| 채팅에서 | 에이전트와 대화하다가 말로 부탁하면 에이전트가 대신 만들어 줍니다. → 아래 소절 | 양식을 채우기 번거로울 때 |
| CLI에서 | 터미널(글자로 명령을 입력하는 창)에서 paseo schedule create 명령으로 만듭니다. → 아래 소절 | 화면이 없는 서버, 스크립트(명령을 순서대로 적어 둔 자동 실행 파일) |
| MCP로 | 에이전트가 Paseo 도구(MCP — 에이전트에게 도구를 쥐여 주는 표준 방식 — 로 주는 Paseo 조작 도구)를 써서 프로그램으로 만들고 관리합니다. 도구 목록은 4장. | 에이전트가 스스로 일정을 짜게 할 때 |
0 9 * * 1-5 — 평일 9시공식 문서는 이 화면에 넣는 항목(에이전트 설정·cron 주기·저장소·프롬프트)과 Archive on finish 스위치가 있다는 것만 밝힙니다. 위 그림은 그 항목을 늘어놓은 것이며, 실제 칸 이름과 배치는 다를 수 있습니다.
채팅에서 만들고 관리하기
양식을 채울 필요가 없습니다. 먼저 Settings → your host → Agents 에서 Enable Paseo tools 를 켜고(기본은 꺼짐 — 4장) 에이전트를 새로 시작한 뒤, 어느 에이전트 채팅에서든 그냥 부탁하면 에이전트가 Paseo MCP(에이전트에게 주는 Paseo 조작 도구 — 4장)를 통해 예약을 만들어 줍니다.
1단계 — 평소 말로 부탁합니다. “언제마다, 무엇을” 해 달라는지만 말하면 됩니다. cron 표기를 몰라도 괜찮습니다. (예시 속 GitHub(코드를 올려 두고 함께 작업하는 웹 서비스)의 이슈는 고칠 점·할 일을 적어 둔 글, PR은 내 변경을 원본에 합쳐 달라는 요청입니다.)
주기
“평일 아침 9시마다”를 cron 주기로 바꿉니다.
에이전트 설정
어떤 에이전트로 돌릴지 정합니다.
프롬프트
실행할 때마다 새 에이전트에게 보낼 부탁 글을 씁니다.
2단계 — 에이전트가 세 가지를 정합니다. 내가 한 말에서 cron 주기, 에이전트 설정, 프롬프트를 골라내고, Paseo MCP로 예약을 만듭니다.
3단계 — 결과를 알려 주고, 관리도 같은 방식으로. 에이전트는 만든 뒤 무엇을 만들었는지 보고합니다. 그다음부터는 멈추기·바꾸기·지우기도 말로 부탁할 수 있습니다.
공식 문서가 드는 예시 프롬프트는 세 가지입니다. 맨 오른쪽 칸에 예약인지 하트비트인지 적었습니다 — 마지막 것은 예약이 아니라 하트비트입니다.
| 이렇게 부탁하면 | 어떤 부탁인가 | 예약 / 하트비트 |
|---|---|---|
| “평일 아침 9시마다 새로 올라온 GitHub 이슈와 PR을 분류하고, 챙겨야 할 것을 요약해 줘.”Every weekday at 9am, triage new GitHub issues and PRs and summarize what needs attention. | 정한 시각마다 되풀이하는 일 | 예약 — 시각이 될 때마다 새 에이전트 |
| “릴리스 빌드가 통과할 때까지 5분마다 확인하고, 실패하면 원인을 고쳐 줘.”Check the release build every 5 minutes until it passes, and fix the cause if it fails. | 끝날 때까지 지켜보는 일 | 원문이 어느 쪽인지 밝히지 않음 — 같은 에이전트가 이어서 지켜보게 하려면 아래 예시처럼 “스스로 깨어나서”를 덧붙입니다 |
| “이 리팩터링을 계속해 줘 — 20분마다 스스로 깨어나서 하던 곳부터 이어서 해.”Keep working on this refactor — wake yourself every 20 minutes and continue where you left off. | 에이전트가 자기 자신을 나중에 깨우는 것 | 하트비트 — 같은 에이전트가 이어 감 |
이미 만든 예약(새 에이전트를 시작하는 쪽)도 같은 방식으로 관리합니다. 공식 문서의 예시는 네 가지입니다.
| 하고 싶은 일 | 이렇게 말합니다 |
|---|---|
| 잠시 멈추기 | “분류 예약을 잠시 멈춰 줘.”pause the triage schedule |
| 주기 바꾸기 | “빌드 확인을 2분마다 돌게 바꿔 줘.”make the build check run every 2 minutes instead |
| 지금 한 번 실행 | “지금 한 번 실행해 줘.”run it once now |
| 지우기 | “지워 줘.”delete it |
같은 관리를 앱의 Schedules 화면이나 CLI에서도 할 수 있습니다. 반면 하트비트는 이렇게 고쳐 쓰는 대상이 아닙니다. 에이전트는 MCP로 자기 하트비트를 만들거나 지울 수만 있고, 바꾸려면 지우고 새로 만듭니다. 이유는 하트비트는 일부러 단순하게에서 설명합니다.
실행이 끝난 워크스페이스 남기기 (Archive on finish)
예약이 한 번 실행될 때마다 Paseo는 그 실행을 위한 워크스페이스(일 하나를 하는 자리. 작업 폴더가 딸려 있음)를 새로 만듭니다. 그리고 기본 설정에서는 실행이 끝나면 그 워크스페이스와 에이전트를 보관(archive)(다 쓴 것으로 표시해 치워 두는 것)합니다. 이 설정의 이름이 Archive on finish(끝나면 보관)이고, 기본값은 켜짐입니다. 예약이 돌았는데 워크스페이스가 보이지 않는다면 이 설정 때문입니다.
실행이 끝나면 Paseo가 그 워크스페이스와 에이전트를 보관합니다. 격리(워크스페이스가 파일을 어떻게 쓸지 고르는 설정 — 2장) 방식에 따라 폴더가 어떻게 되는지가 다릅니다.
- New worktree(워크트리(같은 저장소를 다른 폴더·다른 브랜치로 하나 더 꺼내 놓은 작업 폴더) 격리): 그 워크트리를 쓰던 마지막 활성 워크스페이스가 보관되면 워크트리도 함께 지워집니다.
- Local(이미 있는 폴더를 그대로 쓰는 격리): 워크스페이스만 보관되고 프로젝트 폴더는 그대로 남습니다.
실행 결과를 나중에 열어 보고 싶다면 끕니다. 앱의 Schedules 화면에서 해당 예약을 열고, Archive on finish를 끈 뒤 저장합니다.
- 그 뒤로는 실행마다 생긴 워크스페이스와 에이전트가, 내가 직접 보관할 때까지 활성 상태로 남습니다.
- 다만 에이전트를 만들기도 전에 실패한 실행은 이 설정과 상관없이 정리됩니다.
- 이 스위치는 Local 격리 예약에도 있습니다 — 끄면 그 워크스페이스도 남습니다(보관해도 프로젝트 폴더는 그대로).
- 예약은 정한 시간마다 새 에이전트를 시작하고, 하트비트는 이미 있는 같은 에이전트를 다시 깨워 같은 대화를 이어 가게 합니다. 댓글·멘션 같은 바깥 사건으로 시작하는 것은 Hub(9장)입니다.
- 예약은 앱의 Schedules 화면(기본), 채팅에서 부탁, CLI, MCP 네 길로 만듭니다. 담기는 것은 주기·저장소·에이전트 설정·프롬프트입니다.
- 채팅에서는 “평일 아침 9시마다 …해 줘”처럼 말하면 에이전트가 예약을 만들고, 멈추기·주기 바꾸기·지금 실행·지우기도 말로 부탁합니다.
- 하트비트는 일부러 단순합니다. 만들기와 지우기가 중심이고, 깨울 대상과 프롬프트는 바꿀 수 없습니다.
- 예약 실행이 끝나면 워크스페이스와 에이전트가 기본으로 보관됩니다. 남기려면 앱에서 Archive on finish를 끕니다(앱에서만 가능).
- 주기는 cron 식(분·시·일·월·요일)으로 저장되고 시계에 맞춰 실행됩니다. 시간대 기본은 UTC이고, 만든 직후가 아니라 다음 cron 시각에 처음 돕니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 5장에 있습니다.
브라우저로 직접 확인
Paseo의 에이전트는 “고쳤으니 될 겁니다”라고 말하는 데서 멈추지 않습니다. 내가 데스크톱 앱에서 보고 있는 바로 그 브라우저 탭을 열어, 페이지를 읽고 눌러 보고 스크린샷까지 찍어서 확인합니다. 이 장은 그 기능을 켜는 법, 에이전트가 화면을 읽는 원리, 그리고 안전하게 쓰는 법을 다룹니다.
에이전트가 내 브라우저 탭을 직접 다룹니다
Paseo 데스크톱 앱에서는 워크스페이스(일 하나를 하는 자리. 대화·명령 창·브라우저를 탭으로 엽니다) 안에 브라우저 탭을 열 수 있습니다. 공식 문서가 Browser automation(브라우저 자동화)이라고 부르는 이 기능은, 그 탭을 에이전트(사람 대신 코드를 읽고 고치고 명령을 실행하는 AI 프로그램)가 직접 조작하게 해 줍니다. 에이전트는 개발 서버(만드는 중인 웹 앱을 내 컴퓨터에서 미리 띄워 보는 프로그램)의 페이지를 열고, 내용을 읽고, 순서대로 눌러 보고, 양식을 채우고, 스크린샷을 찍습니다. 이 모든 일이 내 컴퓨터를 떠나지 않고 이루어집니다.
왜 필요할까요? 화면을 만드는 일은 “코드를 고쳤다”로 끝나지 않고 “화면에 실제로 그렇게 보인다”까지 가야 끝납니다. 이 기능은 그 마지막 고리를 에이전트가 스스로 닫게 해 줍니다.
공식 문서가 드는 대표 쓰임새는 네 가지입니다.
자기가 고친 것 확인
화면 부품을 고친 뒤 개발 서버를 열고, 페이지를 읽어 새 글이나 배치가 실제로 거기 있는지 확인합니다.
버그 재현과 원인 찾기
버그 신고에 적힌 순서 그대로 눌러 본 다음, 콘솔(페이지가 남기는 오류·알림 기록)과 네트워크 기록(페이지가 서버와 주고받은 요청 기록)을 읽습니다.
흐름 전체 눌러 보기
양식, 여러 단계로 이어지는 입력 화면, 마우스를 올리면 나오는 메뉴, 끌어다 놓기, 파일 올리기까지 해 봅니다.
로그인된 상태에서 일하기
탭은 로그인 같은 상태를 그대로 유지합니다. 내가 한 번 로그인해 두면 에이전트가 로그인 뒤의 화면에서 일할 수 있습니다.
- “개발 서버를 열어서 방금 바꾼 안내 문구가 실제로 보이는지 확인해 줘.”
- “버그 신고에 적힌 순서대로 눌러 보고, 콘솔에 어떤 오류가 뜨는지 알려 줘.”
- “휴대폰 크기로 줄였을 때 화면이 어떻게 보이는지 스크린샷으로 보여 줘.”
이 기능은 처음에는 꺼져 있고(켜는 방법), 지금은 데스크톱 앱이 있어야 합니다(데스크톱 전용). 사람이 직접 브라우저 탭을 열어 시험하는 방법은 2장과 활용편 3 「결과 검토하고 직접 돌려 보기」에서 다룹니다.
켜는 방법 — 스위치 두 개
브라우저 도구는 기본으로 꺼져 있습니다. 호스트(Paseo의 본체 프로그램인 데몬이 돌아가는 컴퓨터)마다 따로 켭니다.
- 설정에서 에이전트 화면 열기앱에서 Settings → your host → Agents(설정 → 내 호스트 → 에이전트)를 엽니다.
- Browser tools 켜기Browser tools(브라우저 도구) 스위치를 켭니다.
- Enable Paseo tools도 켜져 있는지 보기같은 화면의 Enable Paseo tools(Paseo 도구 사용)도 켜져 있어야 합니다. 브라우저 도구는 Paseo tools(에이전트에게 쥐여 주는 Paseo 조작 도구 묶음. MCP라는 표준 방식으로 전달합니다)의 일부이기 때문입니다. Paseo tools 자체는 4장에서 다룹니다.
- 이미 있던 에이전트는 다시 불러오기처음에는 새 에이전트를 시작하는 쪽이 가장 쉽습니다. 스위치를 켜기 전부터 있던 에이전트는 새 도구를 받으려면 다시 불러오기(reload)가 필요할 수 있습니다.
앱 화면 대신 설정 파일에 한 줄을 적어 켤 수도 있습니다. 방법은 아래 접힌 상자에 있습니다.
에이전트는 화면을 어떻게 읽나 — 스냅샷과 번호표
에이전트는 화면을 주로 글로 읽습니다. 그때 쓰는 것이 스냅샷(snapshot)입니다. 스냅샷은 페이지를 HTML(웹 페이지를 이루는 원본 코드) 그대로가 아니라 접근성 트리(accessibility tree)(페이지를 제목·글·입력칸의 상태·포함 관계로 정리한 목록)로 돌려줍니다. 누를 수 있는 요소에는 @e3 같은 번호표(ref)가 붙습니다.
@e3을 눌러 줘”처럼 번호표로 요소를 가리킵니다.번호표에는 중요한 성질이 하나 있습니다. 그 탭의 가장 최근 스냅샷에서 나온 번호표만 유효하고, 페이지가 바뀌면 만료됩니다. 만료된 번호표를 쓰면 엉뚱한 요소를 누르는 대신 오류가 납니다. 아래에서 한 단계씩 넘겨 보세요.
1단계 — 스냅샷 찍기. 에이전트가 탭의 스냅샷을 요청하면, 페이지 내용이 목록으로 돌아옵니다. 입력칸에는 @e2, 버튼에는 @e3 번호표가 붙었습니다.
2단계 — 번호표로 누르기. 에이전트는 번호표를 건네 “이것을 눌러 줘”라고 합니다. 모든 동작은 대상이 화면에 보이고, 쓸 수 있는 상태이고, 움직임이 멈출 때까지 먼저 기다린 뒤에 실행됩니다.
3단계 — 페이지가 바뀌면 번호표는 만료. 저장 뒤 화면이 달라졌습니다. 예전 @e3은 이제 아무것도 가리키지 않으므로, 다시 쓰면 오류가 돌아옵니다. 잘못된 곳을 누르는 사고를 막는 장치입니다.
4단계 — 새 스냅샷으로 다시 시작. 에이전트는 스냅샷을 다시 찍어 지금 화면에 맞는 번호표를 받고 일을 이어 갑니다. “스냅샷 → 동작 → 스냅샷”이 기본 박자입니다.
스냅샷만으로 부족할 때 쓰는 눈이 두 개 더 있습니다.
스냅샷 주된 방법
페이지를 글 목록으로 받습니다. 번호표가 여기서 나옵니다. 도구 이름은 browser_snapshot.
스크린샷
글 목록에 담기지 않는 것은 화면을 그림으로 찍어 봅니다. 도구 이름은 browser_screenshot.
기록(로그)
콘솔 메시지와 네트워크 요청에 걸린 시간을 읽습니다. 도구 이름은 browser_logs.
- Paseo의 에이전트는 내가 데스크톱 앱에서 보는 바로 그 브라우저 탭을 열어 읽고, 누르고, 스크린샷을 찍어 스스로 확인합니다. 나는 지켜보다가 언제든 끼어들 수 있습니다.
- 기본은 꺼져 있습니다. Settings → your host → Agents에서 Browser tools와 Enable Paseo tools를 둘 다 켜야 하고, 로그인 상태까지 맡기는 것이므로 믿는 에이전트에만 켭니다.
- 지금은 데스크톱 앱이 연결되어 있어야 합니다. 데몬은 브라우저를 직접 돌리지 않고 데스크톱 앱으로 요청을 넘기며, 앱이 없으면 오류를 돌려줍니다.
- 에이전트는 페이지를 스냅샷(글 목록)으로 읽고 번호표로 요소를 가리킵니다. 페이지가 바뀌면 번호표가 만료되어, 엉뚱한 곳을 누르는 대신 오류가 납니다.
- 이동은
http(s)주소만, 올릴 파일은 워크스페이스 안의 것만, 탭은 자기 워크스페이스의 것만 다룰 수 있습니다. - 지켜보며 함께 쓰려면 Paseo 브라우저, 화면 없이 도는 자동 검사나 기존 테스트처럼 독립된 일이면 Playwright 같은 별도 도구가 맞습니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 6장에 있습니다.
어디서나 연결 — 폰 · 웹 · 서버와 보안
에이전트는 내 컴퓨터의 데몬에서 돌고, 휴대폰·웹·다른 컴퓨터는 그 데몬에 연결해서 보고 지시합니다. 이 장은 연결하는 세 가지 길(SSH · Paseo 릴레이 · Tailscale)과 그때 내 코드가 어떻게 지켜지는지, 그리고 웹 화면이나 Docker로 나만의 서버를 꾸리는 방법을 다룹니다.
한 번 더 보는 구조 — 본체와 창
Paseo는 일을 하는 쪽과 들여다보는 쪽이 나뉜 구조입니다. 공식 문서는 이를 Docker(프로그램을 격리된 상자(컨테이너)에 담아 돌리는 도구)와 비슷한 클라이언트-서버 구조(일하는 서버와 들여다보는 클라이언트로 나뉜 구조)라고 설명합니다. 데몬(daemon)(내 컴퓨터나 서버에서 계속 켜져 에이전트와 워크스페이스를 맡아 돌리는 Paseo의 본체 프로그램)은 내 컴퓨터에서 돌면서 코딩 에이전트를 관리합니다. 클라이언트(데몬에 연결해 보고 지시하는 앱 — 모바일 앱, CLI, 웹 화면 등)는 데몬에 연결해 그 에이전트들을 지켜보고 조종합니다.
데몬은 에이전트를 돌리고 싶은 곳이면 어디에나 둘 수 있습니다 — 노트북, Mac Mini, VPS(빌려 쓰는 인터넷상의 서버 컴퓨터), Docker 컨테이너. 그리고 공식 문서는 이렇게 못박습니다. “내 코드는 내 컴퓨터를 떠나지 않는다.” Paseo는 내 개발 환경에 직접 연결하는 local-first(내 컴퓨터에서 먼저, 내 컴퓨터를 중심으로 동작하는) 도구입니다.
연결하는 세 길 — SSH · Paseo 릴레이 · Tailscale
클라이언트가 데몬(내 컴퓨터에서 에이전트를 맡아 돌리는 Paseo 본체)에 닿는 길은 세 가지입니다. 데스크톱 앱(Paseo Desktop)과 CLI(터미널에서 글자 명령으로 쓰는 프로그램)는 SSH로 통로를 뚫어 연결할 수 있고, 휴대폰 앱은 Paseo 릴레이를 거치거나 Tailscale로 직접 연결할 수 있습니다.
| 길 | 쓰는 쪽 | 준비할 것 | 이런 때 |
|---|---|---|---|
| SSH | 데스크톱 앱 · CLI | 상대 컴퓨터에 데몬이 이미 켜져 있고, 그 컴퓨터에 SSH(다른 컴퓨터에 암호화된 통로로 접속하는 표준 방법)로 들어갈 수 있어야 함 | 서버나 다른 컴퓨터에서 도는 데몬을 내 컴퓨터에서 다룰 때 → SSH로 붙기 |
| Paseo 릴레이 | 휴대폰 앱 | 없음. 릴레이를 켜고 QR 코드를 찍으면 끝 — Tailscale, 포트 포워딩(공유기가 바깥 접속을 집 안 컴퓨터로 넘겨 주게 하는 설정), 네트워크 설정이 필요 없음 | 밖에서 폰으로 이어 보려는 대부분의 경우. 공식 문서가 권하는 길 → 릴레이로 짝짓기 |
| Tailscale | 휴대폰 앱 (직접 연결) | 데몬 컴퓨터와 폰 양쪽에 Tailscale(내 기기들끼리만 통하는 사설망(VPN)을 만들어 주는 서비스) 설치, 데몬 설정 한 줄 변경 | 릴레이를 거치지 않고 내 사설망으로 직접 연결하고 싶을 때 → Tailscale 직접 연결 |
크게 보면 연결은 두 종류입니다. 릴레이 연결은 데몬이 Paseo의 중계 서버로 나가는 연결을 걸고 클라이언트가 거기서 만나는 방식이라 열어 둘 포트가 없습니다. 직접 연결은 데몬이 어떤 네트워크 주소에서 기다리고 클라이언트가 그 주소로 곧장 찾아가는 방식입니다(Tailscale이 여기에 듭니다). 어느 쪽이든 실제 통신은 WebSocket(한 번 연결해 두고 양쪽이 계속 주고받는 통신 방식)으로 이루어집니다.
릴레이로 휴대폰 짝짓기
릴레이(relay)(휴대폰과 데몬 사이를 이어 주는 중계 서버)는 휴대폰에서 내 데몬에 연결하는 가장 간단한 방법입니다. VPN 설정도, 포트 포워딩도, 방화벽 설정도 필요 없습니다. 데몬은 내 컴퓨터 안에만 머문 채 릴레이로 나가는 연결을 걸고, 휴대폰이 릴레이에서 데몬을 만납니다. 오가는 내용은 종단간 암호화(보내는 쪽과 받는 쪽만 풀 수 있게 잠그는 것 — 중간의 릴레이는 내용을 못 봄)됩니다.
릴레이는 새로 설치한 상태에서는 꺼져 있습니다. 기기를 짝지으려고 할 때 Paseo가 켤지 먼저 묻고, 켜면 QR 코드와 페어링(QR 코드나 링크로 휴대폰과 호스트를 짝지어 두는 것) 링크가 만들어집니다. 데스크톱 앱에서는 세 단계입니다.
1단계 — 짝짓기 화면 열기. 데스크톱 앱에서 Settings → your host → Pair a device(설정 → 내 호스트 → 기기 짝짓기)를 엽니다. your host 자리에는 내 컴퓨터(호스트)의 이름이 나옵니다.
2단계 — 릴레이 켜기. Enable relay(릴레이 켜기)를 고릅니다. 데몬이 릴레이로 나가는 연결을 걸고, 화면에 QR 코드와 페어링 링크가 나타납니다.
3단계 — 휴대폰으로 찍기. 휴대폰의 Paseo 앱으로 QR 코드를 찍습니다. 카메라로 찍기 어렵다면 페어링 링크를 복사해 휴대폰 앱에 붙여 넣어도 됩니다. 이제 밖에서도 같은 워크스페이스와 대화가 보입니다.
데스크톱 앱 없이 CLI로 켤 때는 호스트의 터미널(글자로 명령을 입력하는 창)에서 명령 하나를 실행합니다.
물음에 확인하면 Paseo가 QR 코드와 페어링 링크를 출력합니다. 휴대폰 앱으로 QR 코드를 찍거나, 앱에서 Paste pairing link(페어링 링크 붙여 넣기)를 골라 링크를 넣습니다.
릴레이를 켜지 않겠다고 답해도 문제는 없습니다. 그 경우 QR 코드는 만들어지지 않고, 데몬은 직접 연결(Tailscale 같은 VPN 등)용으로 그대로 남습니다.
내 코드는 어디로 가나 — 보안의 요점
밖에서 휴대폰으로 연결한다고 하면 가장 먼저 드는 걱정은 “내 코드가 어딘가의 서버에 올라가는 건가?”입니다. 공식 보안 문서의 답은 분명합니다. 코드는 내 컴퓨터를 떠나지 않습니다. 에이전트와 파일은 데몬(내 컴퓨터에서 에이전트를 맡아 돌리는 Paseo 본체)이 있는 컴퓨터에 있고, 휴대폰은 그 화면을 들여다보고 지시를 보낼 뿐입니다.
| 궁금한 것 | 답 |
|---|---|
| 내 코드 · 작업 폴더 | 데몬이 도는 내 컴퓨터(호스트)에만 있습니다. Paseo는 내 개발 환경에 직접 연결하는 도구입니다. |
| 릴레이가 볼 수 있는 것 | IP 주소, 주고받은 시각, 메시지 크기, 세션 ID(연결 하나하나에 붙는 번호)뿐입니다. 메시지 내용과 코드는 읽을 수 없고, 몰래 고치면 들통납니다. |
| 릴레이가 해킹당하면 | 릴레이는 처음부터 믿지 않아도 되게 설계됐습니다. 릴레이가 뚫려도 내 데이터는 보호된 채로 남습니다. |
| QR 코드 · 페어링 링크 | 암호화 연결의 출발점입니다. 비밀번호처럼 다루고 공개된 곳에 올리지 않습니다. |
| 아무 설정도 안 했을 때 | 데몬은 이 컴퓨터 안에서만 연결을 받습니다. 릴레이도 꺼져 있습니다. 밖으로 여는 것은 모두 내가 켜야 합니다. |
| 에이전트 로그인 정보 · API 키 | Claude Code 같은 각 에이전트가 스스로 관리합니다. Paseo는 그 키를 저장하지도, 전송하지도 않습니다. |
릴레이 없이 데몬을 네트워크에 직접 열 때는 이야기가 달라집니다. 그때는 비밀번호를 걸어야 하고, 어디까지 열지 스스로 정해야 합니다. 이어지는 소절들이 그 내용이며, 맨 끝 권장 사항에 한 장으로 모아 두었습니다.
- 일은 데몬이 내 컴퓨터(호스트)에서 하고, 휴대폰·웹·CLI는 거기에 연결하는 창입니다. 공식 문서의 표현으로 코드는 내 컴퓨터를 떠나지 않습니다.
- 연결하는 길은 셋 — 데스크톱 앱·CLI의 SSH, 휴대폰의 Paseo 릴레이(권장)와 Tailscale 직접 연결. Hub는 연결 수단이 아닙니다.
- 릴레이는 처음엔 꺼져 있습니다. Settings → your host → Pair a device → Enable relay 뒤 QR 코드를 찍거나, 터미널에서
paseo daemon pair를 실행합니다. - 릴레이를 지나는 내용은 종단간 암호화되어 릴레이도 읽지 못합니다. QR 코드와 페어링 링크는 비밀번호처럼 다룹니다.
- 데몬은 기본으로 이 컴퓨터 안(
127.0.0.1:6767)에서만 연결을 받습니다. 네트워크에 열 때는 비밀번호를 먼저 걸고, 비밀번호 없이0.0.0.0에 묶지 않습니다. 비밀번호는 출입만 지키고 내용을 암호화하지는 않습니다. - Paseo는 에이전트의 로그인 정보·API 키를 저장하거나 전송하지 않습니다.
- 웹 화면은 데몬이 직접 내줄 수 있고(기본 꺼짐), 도메인·HTTPS로 내놓을 때는 데몬을 localhost에 둔 채 리버스 프록시나 터널만 바깥에 둡니다.
- Docker 이미지는 데몬·CLI·웹 화면을 담고 있지만 에이전트 CLI는 없습니다. 연결하는 두 폴더(
/home/paseo,/workspace)는 에이전트가 써도 되는 범위로 좁게 잡습니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 7장에 있습니다.
설정과 CLI
Paseo의 동작 방식은 설정 파일 한 장(config.json)에 모여 있고, 앱에서 누르던 일은 paseo라는 명령으로도 똑같이 할 수 있습니다. 이 장은 설정이 어디에 있고 어떻게 적용되는지, 말로 지시하는 음성 기능, 제목과 커밋 메시지를 대신 지어 주는 기능, 그리고 paseo 명령을 읽고 쓰는 법을 다룹니다.
설정은 어디에 있나
config.json입니다.
설정을 읽는 쪽은 데몬(daemon)(내 컴퓨터에서 계속 켜져 에이전트와 워크스페이스를 맡아 돌리는 Paseo의 본체 프로그램)입니다. 데몬은 따로 정하지 않으면 ~/.paseo(~는 내 사용자 폴더를 뜻하는 줄임 표기)를 홈 폴더로 쓰고, 설정 파일은 그 안의 ~/.paseo/config.json입니다. JSON(중괄호 안에 “이름: 값”을 적어 나가는 글자 파일 형식)으로 적혀 있어 메모장 같은 편집기로도 열 수 있습니다.
홈 폴더를 다른 곳으로 바꾸려면 PASEO_HOME이라는 환경 변수(프로그램을 켤 때 함께 넘겨주는, 이름 붙은 값)를 정하거나, paseo 명령에 --home 옵션으로 폴더를 지정합니다. 홈 폴더가 다르면 설정도 따로이므로, 원문은 ~/paseo-test 같은 시험용 홈을 하나 더 두는 예를 듭니다.
음성: 받아쓰기와 음성 모드
Paseo는 음성을 정식 기능으로 지원합니다. 쓰임새는 둘입니다. 받아쓰기(dictation)는 내가 한 말을 글자로 바꿔 주는 것이고, 음성 모드(voice mode)는 내 개발 환경과 말로 주고받는 대화입니다. 받아쓰기는 처음부터 켜져 있고, 음성 모드는 Settings > Voice(설정 > 음성)에서 켜기 전까지 꺼져 있습니다.
STT(speech-to-text)(말소리를 글자로 바꾸는 음성 인식)만 있으면 되는 단순한 기능입니다. 이 변환은 내 기기 안에서 전부 처리하게 할 수 있습니다.
음성 모드에는 세 부분이 쓰입니다. 말을 글로 바꾸는 STT, 글을 말로 읽어 주는 TTS(text-to-speech)(글자를 사람 목소리로 바꾸는 음성 합성), 그리고 그 사이에서 무슨 뜻인지 이해하고 무엇을 할지 정하는 부분입니다. 마지막 부분은 화면에 보이지 않는 에이전트 세션이 맡습니다.
왜 이렇게 만들었나 — “내 기기 먼저”. 음성 인식·합성은 전부 내 기기에서 돌릴 수도 있고, 원하면 OpenAI를 고를 수도 있습니다. 말뜻을 이해하고 일을 지휘하는 부분에는 내 컴퓨터에 이미 설치하고 로그인해 둔 프로바이더를 다시 씁니다. 덕분에 자격 증명과 실행이 내 환경 안에 머물고, 음성만을 위한 별도 클라우드 서비스를 끼워 넣지 않습니다.
명령 읽는 법
paseo 명령 한 줄은 띄어 쓴 단어들로 된 짧은 문장입니다. 순서만 알면 처음 보는 명령도 읽을 수 있습니다.
--로 시작하는 단어입니다(짧은 것은 -q처럼 - 하나). 설명서에서 <id>처럼 꺾쇠로 적힌 곳은 실제 값으로 바꿔 넣는 자리입니다.- 에이전트 ID는 줄여 써도 됩니다. ID가
abc123일 때 다른 것과 헷갈리지 않으면abc만 써도 통합니다. ID는paseo ls로 봅니다. - 어느 데몬에게 시키나. 아무것도 지정하지 않으면 기본 홈(
~/.paseo)의 내 컴퓨터 데몬입니다. 다른 데몬에게 시키려면--host(주소로 고름)나--home(홈 폴더로 고름)을 명령 앞이나 뒤 어디에든 붙입니다. - 결과를 어떤 모양으로 받나. 대부분의 명령은 사람이 읽는 표 대신, 다른 프로그램이 읽기 쉬운 형식으로도 내줍니다.
| 어디에나 붙는 옵션 | 뜻 |
|---|---|
--host <대상> | 다른 데몬에 연결합니다. |
--home <폴더> | 그 홈 폴더를 쓰는 내 컴퓨터의 데몬을 고릅니다. |
--json | JSON 형식으로 출력합니다. |
--format yaml | YAML 형식으로 출력합니다. |
-q, --quiet | 최소한만 출력합니다(목록이면 ID만). |
--no-color | 색을 끕니다. |
가장 자주 쓰는 명령
에이전트 하나를 시작해서 멈출 때까지 쓰는 명령은 여섯 가지 안팎입니다. 아래 그림의 순서대로 익히면 됩니다.
paseo를 붙입니다. 예: paseo run "…", paseo ls.paseo run "implement user authentication"
paseo run --provider codex "refactor the API layer"
paseo run --no-wait "run the focused test suite"
- 할 일을 따옴표 안에 적으면 새 에이전트가 그 일을 시작합니다. 사람이 터미널에서 옵션 없이 실행하면, 지금 있는 폴더를 위한 새 Local 워크스페이스가 만들어집니다.
- 기본으로는 에이전트가 끝날 때까지 기다렸다가 돌아옵니다.
--no-wait를 붙이면 바로 돌아오고 에이전트는 계속 일합니다. --provider codex처럼 어떤 프로바이더로 돌릴지 고를 수 있습니다.
paseo ls
돌고 있는 에이전트를 목록으로 보여 줍니다. 정확히는 활성 워크스페이스에 있는, 보관(archive)되지 않은 에이전트입니다. 다른 명령에 넣을 에이전트 ID를 여기서 확인합니다.
paseo send <id> "now run the tests"
paseo send <id> --image screenshot.png "what's wrong here?"
paseo send <id> --no-wait "run this task"
- 일하고 있거나 쉬고 있는 에이전트에게 이어서 할 일을 보냅니다. 받는 에이전트의 ID는
paseo ls에서 보거나 앱의 에이전트 탭에서 복사합니다. --image로 그림 파일을 함께 보낼 수 있고,--no-wait로 답을 기다리지 않고 돌아올 수 있습니다.- 에이전트가 일하는 도중에 사람이 보내면, 기본으로는 하던 차례를 끊고(interrupt) 새 지시로 넘어갑니다.
paseo logs <id> # 처음부터 지금까지 전체
paseo logs <id> -f # 계속 따라가며 보기
paseo logs <id> --tail 10 # 마지막 10개만
paseo logs <id> --filter tools # 도구 호출만
paseo attach abc123 # 실시간 출력에 붙기 (Ctrl+C 로 떼기)
logs는 에이전트가 지금까지 한 일의 기록(타임라인)을 보여 줍니다.attach는 에이전트의 출력을 실시간으로 흘려보냅니다. Ctrl+C를 누르면 보기만 그만둡니다.
paseo wait <id>
paseo wait <id> --timeout 60 # 최대 60초만 기다림
에이전트가 지금 하는 일을 끝낼 때까지 멈춰서 기다립니다. 스크립트에서 “끝나면 다음 줄 실행”을 하거나, 한 에이전트가 다른 에이전트를 기다려야 할 때 씁니다.
paseo stop <id>
에이전트를 멈춥니다. 이름이 비슷해도 데몬을 끄는 명령이 아닙니다 — 데몬을 끄는 명령은 paseo daemon stop으로 따로 있습니다.
- 설정은 Paseo 홈 폴더(기본
~/.paseo)의config.json한 장에 모여 있습니다. 홈 폴더는PASEO_HOME이나--home으로 바꿉니다. - 뒤에서 켠 데몬과 데스크톱 앱은 파일 값을, 터미널에 붙여 켠 데몬과 Docker는 환경 변수를 마지막으로 따릅니다.
- 설정을 바꾼 뒤에는
paseo reload— 안전한 것은 바로 적용되고, 재시작이 필요한 항목은 알려 줍니다. 그때만paseo daemon restart. - 음성은 받아쓰기(기본 켜짐)와 음성 모드(기본 꺼짐) 둘입니다. 내 기기에서 전부 처리할 수 있고(원하면 OpenAI), 기본 로컬 인식 모델은 영어 전용입니다. 음성 모드는 에이전트를 시작·조종할 수 있으니 말로 하는 지시도 조심합니다.
- 워크스페이스 제목·브랜치 이름·커밋 메시지·PR 글은 작은 모델이 뒤에서 대신 짓습니다. 자동이 기본이고, 수동은 내가 고른 모델만 씁니다. 말투는 저장소의
paseo.json으로 정합니다. paseo명령은 “paseo+ 명령 + 대상 + 옵션 + 전할 말” 순서로 읽습니다. 자주 쓰는 것은run(시작) ·ls(목록) ·send(추가 지시) ·logs/attach(지켜보기) ·wait(기다리기) ·stop(멈추기)입니다.paseo stop은 에이전트를 멈춥니다. 데몬은paseo daemon start / stop / restart / status로 다룹니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 8장에 있습니다.
Hub — 바깥에서 부르면 에이전트 시작
지금까지의 Paseo는 내가 앱을 열고 직접 일을 시켰습니다. Hub는 그 위에 얹는 별도 서비스입니다. GitHub에 이슈가 올라오거나 Slack·Discord에서 누군가 봇을 부르면, 그 순간 내 데몬에 에이전트를 시작시키고, 무엇이 도착해 어떤 규칙에 맞았고 무엇이 실행됐는지를 한곳에 기록합니다.
Hub가 무엇이고 무엇을 더해 주나
데몬(daemon)(내 컴퓨터나 서버에서 계속 켜져 에이전트와 작업을 맡아 돌리는 Paseo의 본체 프로그램)은 컴퓨터 한 대에서, 나 한 사람을 위해 에이전트를 돌립니다. Hub는 그 데몬들 위에 놓이는 층입니다. 내 데몬들을 Hub에 등록해 두면, 데몬 혼자서는 할 수 없는 일을 Hub가 더해 줍니다.
공식 문서가 꼽는, 지금 Hub로 얻는 것은 네 가지입니다.
① 스스로 시작하는 에이전트
GitHub·Slack·Discord에서 일어난 일을 계기로, 내가 앱을 열지 않아도 에이전트가 시작합니다.
② 저장소에 두는 규칙
“무슨 일이 생기면 시작할지” 정한 규칙(트리거)을 파일로 저장소(코드와 그 변경 이력이 담긴 프로젝트 폴더)에 두고, 명령 한 줄로 Hub에 올립니다.
③ 빠짐없는 기록
도착한 모든 것, 그것이 어떤 규칙에 맞았는지, 무엇이 실행됐는지가 남습니다.
④ 팀이 함께 보는 한곳
위의 모든 것을 팀이 한 화면에서 봅니다.
헷갈리기 쉬운 것 세 가지를 나란히 놓으면 이렇습니다.
| 무엇 | 하는 일 | 어디서 다루나 |
|---|---|---|
| 릴레이 · SSH 같은 연결 | 내가 다른 기기에서 내 데몬에 접속하는 길입니다. | 7장 |
| 예약 · 하트비트 | 시간에 맞춰 에이전트를 시작하거나 다시 깨웁니다. | 5장 |
| Hub | 바깥에서 생긴 일(이슈, 댓글, 봇 호출)에 맞춰 에이전트를 시작합니다. 연결 수단이 아닙니다. | 이 장 |
Hub를 쓰는 길은 둘입니다. 내 컴퓨터나 서버에서 직접 켜거나, 계정만 만들면 되는 관리형 서비스(Hosted Hub)를 씁니다. 두 쪽 모두 트리거·데몬·기록의 모양은 같습니다(→ 관리형과 직접 운영).
조각들과 “이벤트 → 에이전트” 흐름
Hub는 요청이 도착하는 곳과 에이전트가 도는 컴퓨터를 이어 줍니다. 그 사이에 놓이는 조각은 일곱 가지입니다. 이름이 낯설어도, 뒤에서 하나씩 다시 나옵니다.
앱 연결 (connection)
Hub가 GitHub·Slack·Discord에서 이벤트(“이슈가 열렸다”, “봇이 불렸다” 같은 일 하나)를 받게 해 주는 통로.
데몬 (daemon)
Hub에 등록해 둔, Paseo 데몬이 돌고 있는 컴퓨터 한 대.
Hub 프로젝트 (project)
설정 하나와, 그 설정이 쓰는 앱 연결·데몬을 한데 묶은 단위. 2장의 “프로젝트”(작업 폴더)와는 다른 말입니다.
실행 환경 (environment)
단계가 어디서 도는지에 붙인 이름 — 어느 데몬, 그 안의 어느 작업 폴더, 필요하면 워크트리(같은 저장소를 다른 폴더·다른 브랜치로 하나 더 꺼내 놓은 작업 폴더).
트리거 (trigger)
어떤 이벤트가 일을 시작시킬 수 있는지, 그중 어떤 것만 통과시킬지 정한 규칙.
워크플로 (workflow)
트리거가 맞은 뒤 차례대로 실행되는 단계 묶음.
단계 (step)
에이전트를 한 번 실행하는 것. 단계마다 프롬프트(에이전트에게 주는 지시문), 에이전트 선택, 자격 증명(토큰처럼 “권한이 있다”를 증명하는 것), 답장 능력, 시간 제한이 따로 있습니다.
같은 흐름을 일곱 걸음으로 풀면 이렇습니다.
- 서비스가 Hub에 알립니다.GitHub와 Slack은 웹훅(webhook)(일이 생기면 그 서비스가 정해 둔 주소로 알림을 보내 주는 방식)으로, Discord는 Hub가 미리 걸어 둔 연결(게이트웨이)로, 수동 실행은 Hub API(프로그램이 Hub에 요청을 보내는 창구)로 들어옵니다.
- Hub는 들어온 알림이 정말 그 서비스에서 온 것인지 확인하고, 어디 일인지 알아냅니다.저장소(GitHub), Slack 워크스페이스(Slack에서 회사·팀 공간을 부르는 말 — Paseo의 워크스페이스와 다른 말), 길드(guild — Discord의 서버) 가운데 어느 것에서 온 일인지 가립니다.
- 트리거와 필터를 따집니다.반드시 적어야 하는 허용 목록
from_users(시작시켜도 되는 사람 명단)도 여기서 봅니다. - 맞는 트리거가 있으면 워크플로 실행을 하나 만듭니다.이때 쓰는 것은 그 순간 활성인 설정 개정판(revision)(설정이 바뀔 때마다 남는 한 판. 프로젝트마다 한 번에 하나만 활성)입니다.
- 워크플로가 다음 단계를 따집니다.
if조건이 거짓이면 그 단계를 건너뛰고, 참이면 정해 둔 데몬에서 시작합니다. - 데몬이 에이전트를 시작합니다.Hub는 에이전트의 답장, 정해진 틀에 맞춘 결과, 상태, 완료 여부를 기록합니다.
- 다음 단계가 앞 단계의 결과를 보고 이어 갑니다.남은 단계가 없으면 워크플로 실행이 끝납니다.
from_users가 꼭 있어야 합니다. 설정이 든 저장소는 잘 지켜야 합니다 — 활성 설정을 바꿀 수 있는 사람은 프로젝트가 어떤 앱 연결·데몬·에이전트 능력을 쓸지 고를 수 있기 때문입니다. 그리고 트리거가 GitHub에서 시작됐다고 해서 GitHub 권한이 따라오지 않습니다. 단계에 github 블록을 적었을 때만 그 단계가 권한을 가집니다(→ GitHub 권한). 다만 이 장치들이 에이전트를 가두거나 들어온 글을 안전하게 만들어 주지는 않습니다(→ 보안).빠른 시작 5단계
내 컴퓨터에서 Hub를 켜고, 공개 서버 없이 Slack에 연결한 다음, 채널에서 봇을 부르면 내 저장소에서 에이전트가 답하게 만드는 순서입니다. 브라우저에서 하던 설정이 터미널(글자로 명령을 입력하는 창)로 이어지고, paseo hub init 명령이 시작용 트리거를 대신 써서 올려 줍니다.
| 준비물 | 설명 |
|---|---|
| Paseo | 설치되어 켜져 있어야 합니다(→ 1장). |
| Node.js | 자바스크립트 프로그램을 실행하는 도구. 설치되어 있어야 합니다. |
| Slack 워크스페이스 | Slack에서 회사·팀 공간을 부르는 말입니다(Paseo의 워크스페이스와 다른 말). 내가 앱을 만들 수 있는 곳이어야 합니다. |
1단계 — Hub 켜기. 터미널에서 아래 한 줄을 실행합니다.
npx @getpaseo/hub
출력된 주소(보통 http://localhost:3000 — 내 컴퓨터 안에서만 열리는 주소)를 브라우저로 열고, Hub가 요청하는 운영자 계정을 만듭니다. 처음 켤 때는 데이터베이스(자료 저장 프로그램)도, Docker(프로그램을 격리된 상자에 담아 돌리는 도구)도, 환경 변수(프로그램에 넘겨주는 이름 붙은 설정값)도, API 키(프로그램이 서비스에 접속할 때 쓰는 비밀 열쇠)도 필요 없습니다. Hub가 내장 데이터베이스와 내 조직(organization)을 알아서 만듭니다.
이어서 Home(홈)이 열립니다. “멘션(@이름으로 콕 집어 부르는 것) 한 번에 에이전트가 시작되려면 갖춰져야 할 네 가지” 점검표입니다 — 앱 연결, 데몬 연결, 트리거 만들기, 실행해 보기. 아래 2~5단계가 바로 그 네 가지입니다. Home은 내 조직에 실제로 있는 것을 보고 항목을 채우고, 다음 단계에 필요한 명령을 보여 주며, 넷이 다 끝나면 접힙니다.
2단계 — Slack 연결. Set up your apps(앱 설정하기)가 Slack 앱 만드는 법을 설명하고, Slack에 붙여 넣을 매니페스트(manifest)(앱 설정을 한 번에 적어 둔 글)를 줍니다. 전송 방식은 Socket Mode를 고른 채로 둡니다. Hub 쪽에서 Slack으로 먼저 연결을 거는 방식이라, 바깥에 공개된 주소도 HTTPS(암호화된 웹 주소)도 필요 없습니다.
Slack에서 받은 App-level token(앱 수준 토큰)과 Bot token(봇 토큰)(토큰 — 비밀번호처럼 쓰는 긴 문자열)을 Hub에 붙여 넣고 Connect Slack(Slack 연결)을 누릅니다. 그리고 봇을 쓸 채널에 초대합니다.
/invite @Paseo
GitHub와 Discord는 나중에 해도 됩니다. 설정 화면은 Apps(앱) 아래에 그대로 있습니다.
3단계 — 코드가 있는 컴퓨터 연결. Connect a daemon(데몬 연결)이 이 Hub의 주소가 이미 들어간 명령 한 줄을 보여 줍니다.
paseo hub login http://localhost:3000
이 명령을 코드가 있는 컴퓨터에서, 에이전트가 일할 저장소 폴더 안에서 실행합니다. 다음 단계의 paseo hub init도 같은 폴더에서 실행해야 그 폴더가 트리거의 작업 폴더가 됩니다.
열리는 브라우저 탭에서 로그인을 승인합니다. Hub 탭은 닫지 말고 두세요. 데몬을 지켜보다가 스스로 Daemon connected(데몬 연결됨)를 띄웁니다. 연결되면 Continue(계속)를 누릅니다.
4단계 — 시작용 트리거 만들기. 로그인을 승인하면 터미널이 두 가지를 묻습니다. 둘 다 Yes로 답합니다.
- Connect this daemon to Paseo Hub?(이 데몬을 Paseo Hub에 연결할까요?)
- Allow Hub automations to run agents on this daemon?(Hub 자동화가 이 데몬에서 에이전트를 실행해도 될까요?) — 이 “실행 허락”은 기본값이 아니오이므로 직접 Yes를 골라야 합니다. 아니오로 답했다면 Home이 “연결은 됐지만 에이전트를 실행할 수 없음”이라고 알리고 고치는 명령
paseo hub permissions grant hub.execute를 보여 줍니다.
그다음 아래 명령을 실행합니다.
paseo hub init
Custom endpoint(직접 지정한 주소)를 고르고 http://localhost:3000을 확인합니다. 설정 도우미는 앞에서 한 로그인과 데몬 연결을 그대로 쓰고, 이 트리거에 쓸 수 있는 앱 연결을 보여 줍니다. Slack 워크스페이스가 하나면 자동으로 고르고, 여럿이면 Trigger connection(트리거에 쓸 연결)을 고르게 합니다. 준비된 연결이 하나도 없으면 Hub → Apps로 가라고 안내하고, 에이전트를 고르거나 파일을 쓰기 전에 멈춥니다.
| 묻는 것 | 답할 것 |
|---|---|
| 시작용 에이전트의 프로바이더(Paseo가 실행하는 에이전트 프로그램 한 종류) · 모델 · 모드 | 내 데몬에 있는 Claude, Codex, OpenCode 중 하나. 제안되는 모델과 모드는 그 데몬의 기본값입니다. |
| 내 Slack 멤버 ID | U01234567 같은 값. 봇을 부를 수 있는 단 하나의 계정이 됩니다. 복사하는 곳은 서비스별 트리거 절의 Slack 탭에 있습니다. |
| Deploy now?(지금 배포할까요?) | Yes — 이 트리거를 Hub에서 활성으로 만듭니다. |
도우미는 트리거를 검사한 뒤 저장소에 파일 하나, .paseo/triggers/slack-help.yml을 씁니다. 같은 이름의 파일이 이미 있으면 덮어쓰기 전에 묻고, 다른 파일은 건드리지 않습니다. 배포를 미뤘다면 준비됐을 때 이 저장소에서 paseo hub deploy를 실행합니다.
5단계 — 봇 부르기. 봇을 초대해 둔 채널에서 봇을 멘션(@이름으로 누군가를 콕 집어 부르는 것)합니다.
Hub가 내 데몬에서 에이전트를 시작하고, 에이전트의 답을 그 Slack 스레드(메시지 하나에 달리는 답글 줄기)에 올립니다. 터미널에는 Triggers(트리거) 화면으로 가는 링크가 나오는데, 거기서 트리거를 관리하고 실행 내역을 살펴볼 수 있습니다. 아무 일도 일어나지 않으면 활동 기록이 “필터에 걸린 멘션”과 “어떤 트리거에도 맞지 않은 멘션”을 구분해 알려 줍니다.
~/.local/share/paseo-hub)에 보관합니다. 혼자 쓰는 범위를 넘어서면 직접 운영 절의 배포 방법을 봅니다. 허용 목록을 넓히거나 에이전트에게 GitHub 권한을 주기 전에는 보안 절을 먼저 읽으세요.보안 — Hub가 지켜 주는 것과 내가 지켜야 하는 것
Hub가 하는 일은 세 가지입니다. 들어온 알림이 정말 그 서비스에서 온 것인지 확인하고, 워크플로를 고르고, 에이전트를 데몬에 전달합니다. Hub가 하지 않는 일도 분명합니다. 에이전트 프로세스(실행 중인 프로그램)를 샌드박스(프로그램이 건드릴 수 있는 범위를 가둬 두는 장치)에 가두지 않고, 바깥에서 온 글을 안전하게 만들어 주지도 않습니다.
“실행 허락”이 여는 것부터 정확히 알아 두세요. 데몬을 연결하는 것만으로는 Hub가 에이전트를 돌릴 수 없고, hub.execute를 줘야 합니다. 이 권한 하나가 그 데몬에서 아래 일을 허락합니다.
| hub.execute가 허락하는 것 | 알아 둘 점 |
|---|---|
| 에이전트를 만들고 이어 가기 | 프로바이더 모드에는 승인 요청을 건너뛰는 모드도 들어갈 수 있습니다. 그리고 이 권한은 Hub가 만든 것뿐 아니라 그 데몬에 이미 있던 에이전트와 워크스페이스에도 적용됩니다. Hub가 만든 작업만 둘러싸는 울타리가 아닙니다. |
| 에이전트의 상태와 진행 기록 살펴보기 | |
| 모델 · 생각 깊이 · 프로바이더 권한 모드 정하기 | |
| 워크스페이스를 보관하거나 되살리기 |
데몬 관리, 터미널 조작, 데몬 자격 증명의 권한 관리는 별도의 권한이 있어야 합니다. 그래서 Hub에게 자기 권한을 바꿀 능력을 주지 않은 채로도 hub.execute를 거둘 수 있습니다.
그 위에서 공식 문서가 권하는 습관은 다섯 가지입니다.
① 요청은 믿지 않는다
필터를 좁게 시작합니다. 바깥 트리거에는 from_users를 쓰고, GitHub는 저장소에, Slack은 워크스페이스와 채널에, Discord는 길드와 채널에 못 박습니다. 요청 글은 프롬프트 안에서 “여기부터 여기까지가 요청”이라고 경계를 지어 넣습니다.
② 설정 저장소를 지킨다
.paseo 묶음이 든 저장소에 누가 푸시할 수 있는지 관리합니다. 바꾸는 사람은 앱 연결·데몬·작업 폴더·에이전트·답장 능력을 고를 수 있습니다. 파일이 나뉘어 있다고 권한이 줄지 않으니 한 묶음으로 검토합니다.
③ 작업 폴더를 작게 잡는다
비밀값과 관계없는 저장소는 고른 작업 폴더 밖에 둡니다. 폴더 소유만으로는 부족하다면 전용 OS 사용자(운영체제의 별도 계정), 컨테이너(프로그램을 격리해 돌리는 상자), 가상 머신(컴퓨터 안에 따로 만든 격리된 컴퓨터), 또는 프로바이더 자체의 가두기 기능을 씁니다.
④ 권한은 쓰는 단계에만
여러 단계 워크플로에서는 첫 단계가 요청을 종류별로 나누기만 하고(분류 단계) 뒤 단계가 실제 일을 합니다. 답장 능력은 답하는 단계에만, github 블록은 GitHub가 필요한 단계에만 둡니다. 분류 단계에는 답장도 저장소 권한도 주지 않습니다.
⑤ 고를 수 있는 것을 유한하게
분류 단계가 미리 정한 보기 중 하나만 답하게 하면 요청 글이 뒤 단계의 에이전트·권한을 마음대로 바꿀 수 없습니다. 보기가 정해져 있으니 실행 중에 설정에 없는 프로바이더가 끼어들거나 에이전트에 권한이 더 붙을 수 없습니다. 다만 이것도 겹겹의 방어 가운데 하나일 뿐 샌드박스는 아닙니다.
검토 체크리스트. 바깥 요청을 받는 워크플로를 켜기 전에 일곱 가지를 확인합니다.
- 설정 저장소가 보호되어 있다.
- 바깥 트리거마다 대상(저장소·채널)과 보낸 사람 필터가 좁게 걸려 있다.
- 실행 환경마다 쓸모 있는 범위에서 가장 작은 작업 폴더를 가리킨다.
- (분류 단계를 둔 여러 단계 워크플로처럼 상황에 따라 고르게 만들었을 때만) 상황에 따라 고르는 실행 환경·에이전트 권한에는 정해 둔 보기가 있다.
- 설정 파일에 이름을 붙여 적어 둔 에이전트의 옵션이 고른 프로바이더와 맞고, 빠진 것 없이 완전하다.
- 답장 능력과 GitHub 권한이 그것을 쓰는 단계에만 적혀 있다.
- 프롬프트가 지시문, 요청 글(
${{ paseo.prompt }}), 직접 적어 넣은 이벤트 정보(${{ paseo.context }})를 구분한다.
공식 문서는 워크플로, 설정 참조, 쓰는 서비스의 트리거 설명을 함께 놓고 검토하라고 권합니다(→ 워크플로, 설정 파일과 배포, 서비스별 트리거).
- Hub는 데몬들 위에 얹는 별도 서비스입니다. GitHub·Slack·Discord에서 일이 생기면 내 데몬에 에이전트를 시작시키고, 도착한 것과 실행된 것을 기록합니다. Hub 없이도 Paseo는 그대로 씁니다.
- 흐름은 일이 생김 → Hub가 확인 → 트리거가 거름 → 워크플로가 단계 실행 → 데몬이 에이전트 시작입니다.
- 데몬은 연결과 실행 허락(
hub.execute)이 따로이고, 실행 허락의 기본값은 “아니오”입니다. 데몬이 꺼져 있을 때 온 일은 쌓이지 않으니 다시 일으켜야 합니다. - 트리거에는 허용 목록
from_users가 꼭 있어야 하고, 필터는 전부 통과해야 합니다. 맞는 트리거가 둘이면 둘 다 실행됩니다. - 답을 받으려면 답장 능력을 적고 프롬프트에서
hub.reply와hub.finish_execution을 부르라고 말해야 합니다. GitHub 권한은github블록을 적은 단계에만 생깁니다. - 아무 일도 없을 때는 Activity와 Known unrouted events에서 이벤트가 어디서 멈췄는지부터 봅니다. 가장 흔한 원인은
from_users에 내가 없는 것입니다. - Hub는 요청을 걸러 줄 뿐 에이전트를 가두지 않습니다. 작업 폴더·권한·프로바이더 제한은 내가 좁게 잡아야 합니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 9장에 있습니다.
확장 — 플러그인과 TypeScript SDK
Paseo에 들어 있는 기능만으로 모자랄 때 넓히는 길은 크게 둘입니다. 플러그인은 Paseo 안에 새 화면·버튼·규칙을 더하고, TypeScript SDK는 내가 만든 프로그램이 밖에서 Paseo에게 일을 시키게 해 줍니다. 꼭 직접 만들 필요는 없습니다. 남이 만들어 올려 둔 플러그인은 명령 한 줄로 설치할 수 있습니다.
확장하는 세 길 한눈에
세 길은 “누가, 어디에서 Paseo를 넓히는가”가 다릅니다. 아래 그림에서 데몬(daemon)(내 컴퓨터에서 계속 켜져 에이전트와 작업을 맡아 돌리는 Paseo의 본체 프로그램)을 가운데 두고 보면 쉽습니다. 에이전트(사람 대신 코드를 읽고 고치고 명령을 실행하는 AI 프로그램)를 실제로 돌리는 것은 언제나 데몬이고, 플러그인과 SDK는 그 데몬에 닿는 방향이 서로 다릅니다.
| 길 | 무엇인가 | 이럴 때 필요 | 코딩 |
|---|---|---|---|
| 플러그인 쓰기 | 남이 만들어 게시한 플러그인을 내 데몬에 설치 | Paseo 화면에 없는 패널·버튼·테마·에이전트 종류를 더하고 싶을 때 | 필요 없음 |
| 플러그인 만들기 | TypeScript(자바스크립트에 자료형 검사를 더한 프로그래밍 언어)로 쓴 작은 프로젝트를 데몬에 설치 | 우리 팀만의 화면, 자동 규칙(훅), 새 에이전트 연결이 필요할 때 | 필요 |
| TypeScript SDK | 내 프로그램에서 데몬을 부리는 라이브러리(다른 프로그램에 끼워 쓰는 부품 코드) @getpaseo/client | 이슈·알림이 오면 자동으로 에이전트를 시작하거나, 여러 에이전트의 답을 모으는 프로그램을 만들 때 | 필요 |
| 관련 프로젝트 | 커뮤니티가 만든 도구·연동·설치 묶음 | VS Code 연동, 메뉴 막대 표시, 서버 설치 묶음처럼 이미 누가 만든 것이 있을 때 | 대부분 필요 없음 |
사람이 손으로 치는 paseo 명령(CLI)(글자로 명령을 내리는 방식)도 자동화에 쓸 수 있습니다. 그 내용은 8장에 있습니다. 에이전트 종류(Paseo에서는 프로바이더라고 부릅니다)를 설정 파일만으로 더하는 방법은 3장을 보세요. 이 장의 「프로바이더 플러그인」은 설정으로는 안 되는 에이전트를 코드로 연결하는 경우입니다.
플러그인이란 — 무엇을 더할 수 있나
플러그인(plugin)은 Paseo 데몬 하나에 설치하는 TypeScript 프로젝트입니다. 데몬(에이전트와 작업을 맡아 돌리는 Paseo 본체)에 한 번 설치하면, 화면에 더한 기능은 그 데몬에 연결한 모든 Paseo 앱(휴대폰 포함)에서 함께 나타납니다. 앱마다 따로 설치하지 않습니다.
플러그인은 두 부분으로 이루어집니다. 하나는 Paseo 앱 안에서 돌면서 화면을 그리는 부분이고, 다른 하나는 데몬이 있는 컴퓨터에서 돌면서 파일을 읽거나 외부 서비스에 접속하는 부분입니다. 둘은 RPC(한쪽이 묻고 다른 쪽이 답하는 약속된 호출)로 이야기합니다. 화면이 필요 없는 플러그인은 앱 쪽을, 데몬 쪽 일이 없는 플러그인은 데몬 쪽을 빼도 됩니다.
shared/)을 양쪽이 같이 읽기 때문에 서로 엉뚱한 말을 주고받지 않습니다.플러그인이 더할 수 있는 것은 아래와 같습니다. 이름이 낯설어도 괜찮습니다. “Paseo 화면의 거의 모든 자리에 내 것을 끼워 넣을 수 있고, 데몬 쪽에서는 규칙과 연결을 더할 수 있다”는 점만 잡으면 됩니다.
| 앱 화면에 더하는 것 | 어디에 나타나고 무엇을 하나 |
|---|---|
| 화면(screen) | 플러그인이 통째로 그리는 페이지 하나 |
| 사이드바 항목 | 왼쪽 사이드바(프로젝트와 워크스페이스 목록이 있는 옆 기둥)의 위쪽 목록이나 아래쪽에 넣는 줄. 누르면 플러그인 화면이나 작은 팝업을 엽니다 |
| 사이드바 뷰 | 사이드바의 가운데 내용 전체를 내 방식의 목록으로 바꿔 끼우는 보기 |
| 워크스페이스·에이전트 패널 | 워크스페이스(일 하나를 하는 자리) 안에서 에이전트·터미널·파일 옆에 탭으로 열리는 칸 |
| 파일 패널 | 정해 둔 종류의 파일을 열었을 때 그 파일을 보여 주거나 고치는 탭 |
| Command Center 항목 | ⌘K(macOS) / Ctrl+K(Windows·Linux)로 여는 명령 검색창에 뜨는 항목 |
| 슬래시 명령 | 메시지 입력칸에 /이름을 쳐서 실행하는 명령(에이전트에게 보내지 않고 앱이 처리) |
| 헤더 버튼 · 컴포저 필 | 워크스페이스 머리줄의 버튼, 그리고 에이전트 입력칸 바로 위에 뜨는 알약 모양 버튼 |
| 컴포저 항목 | 메시지 입력칸(composer) 안에 넣는 토글·선택 상자·버튼 |
| New workspace 항목 | 새 워크스페이스 만들기 화면에 더하는 입력 칸 |
| 타임라인 항목 | 에이전트와의 대화 기록(타임라인)에서 한 줄을 플러그인 모양으로 바꾸거나 새 줄을 끼워 넣기 |
| 테마 | Settings → Appearance(설정 → 모양)에 뜨는 밝은·어두운 색 조합 |
| 설정 화면 | Settings → Plugins(설정 → 플러그인)의 내 플러그인 줄에서 여는 플러그인 전용 설정 |
| 첨부 소스 | 입력칸에서 외부 자료(예: 이슈)를 검색해 프롬프트(에이전트에게 보내는 지시문)에 붙이는 메뉴 |
| 데몬 쪽에 더하는 것 | 무엇을 하나 |
|---|---|
| 데몬 쪽 처리기(RPC) · 스트림 | 앱 쪽이 물으면 답하는 처리기, 그리고 변화가 생길 때마다 앱으로 계속 보내 주는 통로 |
| 훅(hook) | 워크스페이스·에이전트가 만들어지거나 일을 마치는 순간에 끼어드는 자동 규칙 |
| 프로바이더 | 새 종류의 코딩 에이전트를 Paseo에 연결. 프로바이더(provider)(Paseo가 실행하는 에이전트 프로그램 한 종류)를 Paseo 본체를 고치지 않고 더합니다 |
| 사용량 소스 | 계정의 남은 사용 한도를 읽어 와 보여 주는 출처 |
| 평소 Paseo 조작 | 워크스페이스·에이전트·터미널 만들기 같은 보통 작업을 SDK로 수행 |
설치 범위는 데몬 하나입니다. 호스트(host)(데몬이 돌아가는 컴퓨터)가 여러 대라면 쓰려는 호스트마다 설치합니다. 같은 플러그인이 연결된 여러 호스트에 있으면 Paseo는 사이드바 항목을 하나만 보여 주고 호스트를 고르는 상자를 붙입니다. 또 호스트마다 플러그인 기능 전체를 켜고 끄는 큰 스위치 Enable plugins(플러그인 사용)가 있어서, 이 스위치와 플러그인 각각의 스위치가 둘 다 켜져야 플러그인이 돕니다.
게시된 플러그인 설치하기
플러그인을 만들 생각이 없어도 됩니다. 다른 사람이 만들어 플러그인 레지스트리(검토를 거친 플러그인을 모아 둔 공개 목록)에 올린 것을 골라 설치하면 됩니다. 목록은 paseo.sh/plugins에서 둘러봅니다. 레지스트리로 설치하면 Paseo는 검토자가 확인해 둔 바로 그 버전을 받아 옵니다.
Reviews changes before merge — 줄마다 상태와 설명이 보이고, ⋯ 메뉴에 설정 · Logs(기록) · Reload(다시 불러오기) · Remove(제거)가 있습니다.
- 플러그인 기능 켜기설치할 호스트의 Settings → Plugins(설정 → 플러그인)에서 Enable plugins를 켭니다. 그 데몬의 모든 플러그인에 적용되는 큰 스위치입니다.
- 설치하기Plugin source(플러그인 출처) 칸에 레지스트리의
소유자/이름을 붙여 넣고 Install plugin(플러그인 설치)을 누릅니다. 명령 창에서는paseo plugin add owner/slug한 줄입니다. 화면이 호스트를 업데이트하라고 하면 그 호스트의 Paseo를 먼저 업데이트합니다. - 확인하고 쓰기설치된 플러그인 줄에 상태와 설명이 나타납니다. 상태가
running(실행 중)이면 된 것입니다. 줄의 스위치로 켜고 끄고, 점 세 개(⋯) 메뉴에서 설정·기록·다시 불러오기·제거를 합니다. - 업데이트하기
paseo plugin update <플러그인 ID>는 새 버전이 있으면 지금 버전과 바꿀 버전을 보여 주고 승인을 물은 뒤 바꿉니다. 거절하면 그대로 둡니다.--all을 붙이면 전부 확인합니다.
running인지 ③ 지금 앱이 그 플러그인을 설치한 호스트를 보고 있는지. 데몬 쪽 오류는 paseo plugin logs <플러그인 ID>나 ⋯ 메뉴의 Logs에서 읽습니다.
레지스트리 밖의 것도 설치할 수 있습니다. 같은 칸(또는 같은 명령)에 Git 저장소(코드와 그 변경 기록을 보관하는 곳) 주소, npm(자바스크립트 꾸러미를 올리고 받는 공개 창고) 꾸러미 이름, 데몬 컴퓨터의 폴더 경로를 넣으면 됩니다. 이때는 검토를 거치지 않은 코드일 수 있으니 더 조심합니다. 적는 형식과 명령 전체는 아래 상자에 있고, 같은 명령 표가 8장에도 있습니다.
TypeScript SDK란
정식 이름은 @getpaseo/client이고, TypeScript(자바스크립트에 자료형 검사를 더한 프로그래밍 언어)로 쓰는 라이브러리(다른 프로그램에 끼워 쓰는 부품 코드)입니다. 프로그램은 프로바이더(Paseo가 실행하는 에이전트 프로그램 한 종류)와 모델을 고르고, 에이전트에게 프롬프트(지시문)와 작업 폴더를 건네고, 답을 기다립니다.
중요한 점은 일은 데몬이 한다는 것입니다. 데몬(에이전트를 맡아 돌리는 Paseo 본체)이 에이전트 프로그램을 띄우고, 세션을 살려 두고, 그 진행을 Paseo 앱으로 보내 줍니다. 내 프로그램은 앱과 똑같이 데몬에 연결한 클라이언트일 뿐입니다. 그래서 SDK로 만든 에이전트는 내가 손으로 시작한 에이전트와 나란히 Paseo에 보이고, 프로그램이 끝난 뒤에도 그대로 남습니다.
공식 문서가 드는 쓰임새는 네 가지입니다.
들어온 일을 코딩 작업으로
이슈, 경보, 웹훅(다른 서비스가 “일이 생겼다”고 알려 주는 자동 호출)이 오면 에이전트를 시작합니다.
여러 에이전트를 동시에
에이전트 여러 개를 나란히 돌리고 답을 모읍니다.
세션을 열어 두고 이어서
세션(에이전트와 이어지는 대화 하나)을 유지하면서 뒤따르는 지시를 보냅니다.
현황판 만들기
내 에이전트들을 한눈에 보는 대시보드를 만듭니다.
같은 기능 묶음을 플러그인 안에서도 그대로 쓸 수 있습니다(데몬 쪽에서 할 수 있는 일). 프로그램을 짜지 않고 명령 창에서 자동화하려면 8장의 CLI를, 에이전트가 스스로 다른 에이전트를 부리게 하려면 4장을 보세요.
- 넓히는 길은 셋입니다. 플러그인은 데몬에 설치되어 Paseo 안에 기능을 더하고, SDK(
@getpaseo/client)는 내 프로그램이 밖에서 데몬에게 일을 시키게 하며, 관련 프로젝트는 커뮤니티가 만든 주변 도구입니다. - 플러그인은 데몬 하나에 설치하고, 화면 기능은 그 데몬에 연결한 모든 앱에 나타납니다. 격리 장치 없이 도는 코드이므로 설치는 그 코드와 앞으로의 업데이트를 믿는다는 뜻입니다.
- 남이 만든 플러그인은 Enable plugins를 켜고
paseo plugin add owner/slug(또는 설정 화면)로 설치합니다. 상태가running이면 된 것입니다. - 만드는 순서는 뼈대 → 설치해 보기 → 기능 더하기 → 다시 불러오기 → 기록 읽기이고, 코드를 둔 폴더가 도는 곳을 정합니다.
- 훅은 워크스페이스·워크트리·에이전트의 14개 순간에 끼어듭니다. Paseo가 기다리는 훅은 30초 안에 내용을 바꿀 수 있고, 알림은 보기만 합니다.
- SDK의 기본 흐름은 연결 → 에이전트 만들기 → 답 기다리기 → 끊기입니다. 일은 데몬이 하므로 프로그램이 끝나도 에이전트는 남고, 임시 에이전트는 직접 보관합니다.
- 프로바이더 옵션은 에이전트의 행동을 제한할 뿐 컴퓨터를 지키는 벽이 아닙니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 10장에 있습니다.