터미널 Claude Code 세션을 Paseo 앱으로 넘기는 gaseo 플러그인

터미널에서 claude 를 띄워 한참 작업하다가 자리를 떠야 할 때가 있습니다. 그 대화를 폰에서 그대로 이어받으려면 방법이 마땅치 않습니다. Paseo 는 코딩 에이전트를 사용자 자신의 기기에서 돌리고 폰이나 웹에서 조종하는 자체 호스팅 도구인데, 목록에 뜨는 것은 기본적으로 Paseo 가 직접 띄운 에이전트입니다. gaseo 는 터미널에서 시작한 Claude Code 세션을 그 목록에 끼워 넣어 주는 Claude Code 플러그인입니다.

규모부터 밝힙니다. gaseo 저장소는 스타 3개짜리 개인 프로젝트입니다. 만든 사람은 fivetaku, 라이선스는 MIT 이고 저장소가 만들어진 것은 2026년 8월입니다. 나온 지 며칠 안 된 물건이라 널리 검증됐다고 말할 수 없습니다. 다만 이게 건드리는 문제는 실제로 있는 문제이고, 안에 든 설계 판단 하나는 다른 도구를 고르거나 만들 때도 그대로 써먹을 만합니다. 이 글은 플러그인 사용법과 그 판단을 같이 봅니다.

Paseo 는 어디서 무엇을 돌리는가

Paseo 는 여러 코딩 에이전트를 한 인터페이스에서 굴리는 오픈소스입니다. 저장소는 getpaseo/paseo 이고 2025년 10월에 생겼습니다. 이 글을 쓰는 시점 GitHub 스타는 12,669개, 저장소에 표기된 라이선스는 AGPL-3.0 입니다. gaseo 와는 자릿수가 다른 프로젝트라, 두 도구를 같은 무게로 놓고 읽으면 안 됩니다.

구조의 핵심은 데몬이 어디서 도느냐입니다. 데몬은 사용자 기기에서 돕니다. 노트북이어도 되고 홈서버나 VPS 여도 됩니다. 클라이언트는 거기 붙을 뿐입니다. 문서의 표현이 정확합니다. "Paseo manages other agents, it doesn't ship one." 자체 에이전트를 파는 게 아니라 이미 깔려 있는 CLI 를 감싸 관리한다는 뜻이고, 그래서 Claude Code 든 Codex 든 사용자가 먼저 설치하고 인증까지 끝내 둬야 합니다. 설정과 상태는 PASEO_HOME, 보통 ~/.paseo 아래에 남습니다. 세션도 시스템 프롬프트도 MCP 서버도 그 기기를 벗어나지 않는 구성입니다.

붙는 경로는 여러 갈래입니다. 데스크톱 앱은 macOS(Apple Silicon/Intel), Windows(x64/ARM64), Linux(AppImage/DEB/RPM) 로 나오고 데몬을 자체 내장합니다. 모바일은 App Store 와 Play Store 에 앱이 있고 APK 직접 설치도 열려 있습니다. 헤드리스로 쓰려면 npm install -g @getpaseo/cli 로 CLI 를 깔고 paseo 를 띄우면 되는데, 이 데몬이 웹 UI 도 같이 서빙합니다. Docker 이미지는 6767 포트로 돕니다. 네이티브로 지원하는 프로바이더는 Claude Code, Codex, OpenCode, pi 이고 ACP 카탈로그를 통해 Cursor, Gemini, GitHub Copilot 같은 것들이 더 붙습니다. 기능 쪽에서는 git worktree 로 에이전트를 격리 브랜치에 묶는 것, 도는 에이전트에 붙어 출력을 실시간으로 보는 것, 완료 푸시 알림이 눈에 띕니다.

터미널 세션이 목록에 없다는 문제

gaseo README 첫머리 문장이 문제를 그대로 짚습니다. "Your terminal sessions are invisible to Paseo." 앱 목록에는 Paseo 가 띄운 에이전트가 뜹니다. 셸에서 claude 를 쳐서 시작한 세션은 거기 없습니다. 실제 작업 대부분이 그렇게 시작한다는 걸 생각하면 꽤 큰 구멍입니다. gaseo 는 그 세션을 등록해 목록에 올려 줍니다.

다만 한 가지는 짚고 가야 합니다. gaseo README 는 "there's no import button in the UI" 라고 적었는데, Paseo 변경 이력을 열어 보면 0.1.71(2026년 5월 9일) 항목에 "Import existing Claude, Codex, and OpenCode sessions into Paseo — pick up a conversation you started in the terminal and keep going from the app, with the full timeline" 이 올라와 있습니다. CLI 쪽 paseo import --provider <name> <id> 는 그보다 앞선 0.1.65(5월 3일)에 들어왔습니다. 터미널 세션을 가져올 방법이 아예 없는 상태는 아니라는 뜻이니, README 문구를 그대로 믿지 말고 자기가 쓰는 Paseo 버전에서 직접 확인하는 편이 낫습니다.

그러면 gaseo 가 남기는 값은 무엇이냐. 절차입니다. Paseo 쪽 가져오기를 쓰려면 어느 세션인지 골라야 하고, 그 순간 손이 앱으로 넘어갑니다. gaseo 는 지금 타이핑하고 있는 그 창에서 /gaseo 한 줄로 끝냅니다. 자리에서 일어나기 직전 몇 초짜리 동작으로 만드는 것이 이 플러그인이 파는 전부입니다. 사슬로 보면 이렇습니다. 데몬이 켜져 있어야 하고, 세션이 등록돼 있어야 하고, 폰에서 그 세션을 열 수 있어야 합니다. 첫째와 셋째는 Paseo 몫이고 gaseo 는 가운데 고리 하나만 맡습니다. Nginx 액티브 헬스체크 모듈을 소스에서 패치해 설치하는 식으로 빌드가 길게 늘어지는 작업이라면, 자리를 뜨면서 세션만 넘겨 두고 결과를 폰에서 확인하는 그림이 나옵니다.

설치와 명령

설치는 마켓플레이스를 추가하고 플러그인을 까는 두 줄입니다.

/plugin marketplace add https://github.com/fivetaku/gptaku_plugins.git
/plugin install gaseo

설치 뒤에는 Claude Code 를 다시 띄워야 합니다. 새 슬래시 명령은 재시작해야 등록되기 때문입니다. 이 단계를 건너뛰면 /gaseo 가 인식되지 않아 설치가 실패한 것처럼 보입니다.

/gaseo               # 지금 이 세션 등록
/gaseo past          # 이 폴더의 과거 세션 목록에서 골라 등록
/gaseo <folder>      # 다른 폴더의 현재 세션 등록
/gaseo past <folder> # 다른 폴더의 과거 세션 목록

슬래시 명령 말고 자연어로도 부를 수 있습니다. "파세오로 가세오", "이 세션 파세오로 가세오", "과거 세션 파세오로 가져와줘" 같은 한국어 문장과 "register this session to paseo", "import my past sessions into paseo" 같은 영어 문장이 트리거로 걸려 있습니다. 전제 조건은 세 가지입니다.

• Claude Code CLI
• Paseo 설치, 데몬 실행 상태(paseo status 로 확인)
• paseo CLI 가 PATH 에 있거나 기본 설치 위치에 있을 것

셸을 그리 자주 쓰지 않는다면 리눅스 필수 명령어와 터미널 사용법을 한 번 훑고 PATH 확인부터 하는 편이 빠릅니다. 등록이 안 될 때 원인의 상당수가 데몬이 안 떠 있거나 paseo 를 못 찾는 경우입니다.

gaseo 저장소에서 README 확인하기Paseo 내려받기 페이지 열기

복사가 아니라 링크라는 판단

동작 순서는 단순합니다. 먼저 이 폴더에 해당하는 세션 디렉터리를 찾습니다. Claude Code 는 ~/.claude/projects/ 아래에 폴더 경로의 영숫자 아닌 문자를 - 로 바꾼 이름의 디렉터리를 만들고, 그 안에 세션 UUID 를 파일명으로 한 .jsonl 트랜스크립트를 씁니다. 직접 열어 보면 바로 확인됩니다. 그다음 $CLAUDE_CODE_SESSION_ID 를 읽어 지금 세션을 특정하고, ~/.paseo/agents 에 이미 있는지 본 뒤, 없으면 paseo import <sessionId> --provider claude --cwd <folder> 를 실행합니다. 이미 등록된 세션은 다시 넣지 않고 보고만 하고 끝냅니다. Paseo 가 한 번도 본 적 없는 폴더라면 워크스페이스가 그 자리에서 만들어집니다.

여기서 볼 대목은 README 의 이 한 줄입니다. "It's a link, not a copy." Paseo 는 대화 내용을 자기 쪽에 따로 쌓지 않습니다. 에이전트 레코드가 들고 있는 것은 persistence.nativeHandle 에 담긴 Claude 세션 ID 포인터뿐이고, 트랜스크립트는 Claude Code 가 써 둔 자리에 그대로 남습니다.

왜 이게 맞는 선택인지는 반대쪽을 상상해 보면 드러납니다. 가져오기가 복사였다면 같은 대화가 두 벌 생깁니다. 터미널에서 한 턴 더 돌리고 앱에서도 한 턴 더 돌리는 순간, 어느 쪽이 최신인지 정하는 규칙이 필요해집니다. 병합 규칙을 정해야 하고 충돌을 처리해야 하고 동기화 주기를 잡아야 합니다. 세션 하나 옮기자고 분산 상태 문제를 새로 만드는 셈입니다. 포인터만 두면 원본은 끝까지 하나입니다. Paseo 에서 에이전트를 나중에 아카이브해도 원래 대화는 손상되지 않습니다. 가져오기가 즉시 끝나고 데몬 재시작이 필요 없는 이유도 여기 있습니다. 옮길 데이터가 애초에 없으니까요.

이건 gaseo 만의 이야기가 아닙니다. 상태를 옮기거나 이어받는 도구를 고를 때 먼저 물어야 할 것은 "원본이 어디 하나로 정해져 있는가" 입니다. 이 질문에 답이 없는 도구는 편해 보이는 만큼 나중에 값을 치릅니다. EKS 에서 Vault Raft 클러스터가 깨져 Pod 와 PVC 를 지우고 다시 세우는 복구 작업이 고약한 이유도 결국 같은 자리에 있습니다. 어느 사본이 진짜인지 시스템이 스스로 판정하지 못하면 사람이 손으로 정해 줘야 합니다.

지금 기대면 안 되는 부분

README 의 "Notes and limits" 가 제법 솔직하게 쓰여 있어서, 그 내용을 그대로 옮겨 둘 값이 있습니다.

• Codex 세션 미지원. 폴더가 아니라 날짜 기준으로 저장돼 폴더-세션 매핑이 성립하지 않음
• 데몬 자동 재시작 없음. paseo import 가 실패하면 보고하고 멈춤
• 세션 특정이 어긋날 여지. $CLAUDE_CODE_SESSION_ID 를 못 쓰면 가장 최근에 쓰인 트랜스크립트를 고르는 추측으로 내려감

데몬을 자동으로 살리지 않는 이유는 납득할 만합니다. 재시작하면 돌고 있던 에이전트가 전부 죽기 때문에, 그 판단은 사람 몫으로 남겨 뒀다는 것입니다. 세션 특정 쪽은 좀 더 신경 써야 합니다. 백그라운드 서브에이전트나 훅이 띄운 세션이 같은 디렉터리에 더 최근 파일을 쓰는 일이 흔한데, 그러면 mtime 추측이 엉뚱한 세션을 집습니다. gaseo 는 출력에 어느 경로를 썼는지 via=env 또는 via=mtime 으로 라벨을 찍고 고른 세션의 첫 메시지를 보여 줍니다. via=mtime 이 뜨면 그 첫 메시지를 눈으로 확인하거나 /gaseo past 로 직접 고르는 쪽이 안전합니다. Codex 세션이 필요하다면 gaseo 대신 Paseo 자체 가져오기를 보는 것이 맞습니다. 변경 이력에는 Codex 도 대상에 들어가 있습니다.

프로젝트 성격도 다시 말해 둡니다. 스타 3개, 공개 며칠, 개인 계정입니다. 저장소는 fivetaku 개인 계정에 있고 Paseo 를 관리하는 getpaseo 조직 소속이 아니며, 동봉된 DISCLAIMER 에도 제3자 프로젝트와의 비제휴 조항이 들어 있습니다. 중요한 작업 흐름을 여기 걸어 두면 안 됩니다. 잃어도 되는 세션으로 먼저 돌려 보고, 등록된 내용이 앱에서 제대로 열리는지 확인한 다음에 습관으로 굳히는 순서가 맞습니다. 새로 나온 에이전트 부속을 볼 때 무엇부터 확인해야 하는지는 AI 스킬 디렉터리를 검증하며 정리한 기준과 겹치는 부분이 많습니다.

Paseo 변경 이력터미널 세션 가져오기가 어느 버전에 들어왔는지 확인 getpaseo/paseo데몬과 프로바이더 구현을 직접 읽어 볼 수 있는 저장소

정리

• Paseo 는 데몬을 사용자 기기에서 돌리고 폰이나 웹에서 붙는 오픈소스입니다. 에이전트 CLI 는 직접 설치해 둬야 합니다.
• gaseo 는 터미널에서 시작한 Claude Code 세션을 /gaseo 한 줄로 Paseo 에 등록하는 플러그인입니다. 설치 후 재시작이 필요합니다.
• 대화를 복사하지 않고 세션 ID 포인터만 남깁니다. 원본이 하나로 유지되니 어느 쪽이 최신인지 다툴 일이 없습니다.
• Codex 세션은 대상이 아니고, via=mtime 으로 잡힌 세션은 첫 메시지를 확인해야 합니다. 데몬이 죽으면 알아서 살아나지 않으니 재시작은 직접 판단해야 합니다.
• 스타 3개짜리 신생 프로젝트에 개인 계정 저장소입니다. 값진 세션을 여기 맡기기 전에 버려도 되는 세션으로 먼저 시험해 보고, Paseo 자체 가져오기와 무엇이 다른지 자기 버전에서 확인하세요.

출처: gaseo 저장소, Paseo 공식 사이트, Paseo 변경 이력, Paseo 문서, getpaseo/paseo 저장소