Pi Agent

English | 简体中文

pi-agent-desktop은 macOS와 Windows용 로컬 AI 에이전트 데스크톱 애플리케이션입니다. 이는 pi의 에이전트 기능을 독립적이고 설치 가능한 애플리케이션으로 패키징했습니다.

기능 (Features)

• 터미널 기록이나 .jsonl 파일을 뒤지기 않고도 프로젝트별로 이전 Pi 세션을 검색하고 재개할 수 있습니다.
• 데스크톱 창 안에서 에이전트와 실시간으로 대화하며, 생각 과정(thinking), 도구 호출(tool calls), 컨텍스트 사용(context usage), 비용(cost), 그리고 압축 상태(compaction state)를 모두 확인할 수 있습니다.
• 이전 메시지부터 브랜치로 이어가거나, 대화를 독립적인 세션으로 포크할 수 있습니다.
• 모델, OAuth/API 키, 사용자 지정 모델 구성, 스킬(skills), 플러그인(plugins)을 관리합니다.
• 사이드바에서 Git 작업 트리(worktrees)를 전환하고 프로젝트 파일을 탐색할 수 있습니다.
• 예약된 작업: 저장된 프롬프트를 일정에 따라 새 세션에서 실행할 수 있습니다 (시간별, 일일, 주간, 사용자 지정 cron 표현식 또는 단발성). 이 기능은 앱이 열려 있는 동안(창이 숨겨져 있어도) 작동하며, 기본적으로 읽기 전용 도구로 실행되고, 슬립 후 한 번 따라잡은 다음, 실행 성공 또는 실패 시 알림을 제공합니다.
• 소스 코드, diff, Markdown, 이미지, 오디오, PDF, DOCX 파일을 미리 볼 수 있습니다.
• 다크 모드, 자동 세션 이름 지정, 완료 사운드, 복원된 실행 상태를 지원합니다.
• 최신 안정 버전의 pi-agent-desktop GitHub 릴리스에 대한 주간 확인을 제공하며, 설치된 앱이 오래되었을 경우에만 인앱 알림을 표시합니다.
• 업그레이드 버튼 하나로 Pi Agent의 완전하고 서명된 새 빌드를 설치하고 자동으로 재시작합니다.

⬇️ Pi Agent 다운로드 (macOS / Windows)

Repository: abcwyc/pi-agent-desktop

설치 및 사용법 (Installation And Usage)

데스크톱 앱 설치 (Install The Desktop App)

빌드는 GitHub Releases에서 이용 가능합니다:

• Apple Silicon Mac: aarch64.dmg를 다운로드하여 열고 앱을 Applications 폴더로 드래그하세요. 공식 릴리스는 Intel Mac용으로 빌드되지 않습니다.

• Homebrew가 설치된 Apple Silicon Mac: 이 저장소의 tap에서 설치할 수 있습니다. tap은 저장소 URL에서 추가되므로, 첫 번째 명령어는 한 번만 필요합니다:

  복사

brew tap abcwyc/pi-agent-desktop https://github.com/abcwyc/pi-agent-desktop
brew install --cask pi-agent

이 앱은 설정(Settings)에서 자체적으로 업그레이드되므로, `brew upgrade`는 `--greedy` 옵션을 전달하지 않는 한 건드리지 않습니다. `brew uninstall --cask --zap pi-agent`를 사용하면 앱과 창 상태는 제거되지만, pi CLI가 공유하는 `~/.pi` 폴더는 삭제되지 않습니다.
- Linux x64: `.deb` 패키지를 다운로드하여 배포판의 패키지 관리자로 설치하세요. 커뮤니티에서 유지 관리하는 Flatpak도 [flatpark.org](https://flatpark.org/apps/io.github.abcwyc.pi-agent-desktop/)에서 이용 가능합니다. 공식 릴리스는 아니지만, Flatpak은 대부분의 배포판에서 작동하며 업데이트를 처리해 줍니다.

- Windows x64: 이름이 `x64-setup.exe`로 끝나는 설치 파일을 다운로드하여 실행하세요. 이 설치 프로그램은 Microsoft WebView2가 누락된 경우 자동으로 가져와(pull in) 설치합니다.

공식 릴리스는 macOS 11 이상을 실행하는 Apple Silicon Mac, Windows 10/11 x64, 그리고 WebKitGTK 4.1 및 GTK 3를 사용하는 Linux x64 배포판을 지원합니다. 데스크톱 패키지에는 Next.js 서버, Node.js 런타임, 최신 Pi SDK가 번들되어 있어 앱과 함께 로컬 서버가 시작됩니다. 따라서 별도의 터미널, Node.js 설치 또는 수동으로 시작하는 웹 서버가 필요하지 않습니다.

> Pi Agent를 설치하면 앱 내부에 에이전트가 생기지만, 전역 `pi` 명령어를 설치하지는 않습니다. 만약 터미널에서도 Pi CLI를 사용하고 싶다면, [pi 프로젝트](https://github.com/earendil-works/pi)의 지침을 따라 별도로 설치하세요.

**macOS에서 첫 실행 시 차단**: macOS 빌드는 Apple Developer ID로 서명되지 않았거나 Notarize(공증)되지 않았기 때문에 Gatekeeper가 개발자를 확인할 수 없다고 하거나 앱이 '손상되어 열 수 없습니다'라고 표시할 수 있습니다 (Homebrew 설치 포함). 시스템 설정 > 개인 정보 보호 및 보안에서 '어쨌든 열기(Open Anyway)'를 클릭하거나 다음 명령을 실행하세요:

```bash
xattr -dr com.apple.quarantine "/Applications/Pi Agent.app"

서명된 자동 업데이트가 처음 사용되려면, 업데이터가 없는 이전 빌드를 수동으로 서명된 버전으로 교체해야 합니다. 그 후에는 설정(Settings)에서 업그레이드가 이루어집니다.

기존 Pi 데이터 사용하기

Pi Agent는 기본적으로 Pi의 로컬 데이터 디렉터리를 읽습니다:

~/.pi/agent/

세션은 일반적으로 다음 위치에 저장됩니다:

~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl

이전에 이 장치에서 Pi를 사용한 적이 있다면, 앱 설치 후 기존 세션, 모델 및 인증 정보를 자동으로 가져옵니다. PI_CODING_AGENT_DIR을 설정하여 다른 Pi 에이전트 데이터 디렉터리를 가리키게 할 수 있습니다.

모델 키와 세션 데이터는 귀하의 장치에 남아 있습니다. 파일 탐색 API는 현재 세션, 선택된 프로젝트 및 명시적으로 승인된 작업 디렉터리에만 접근을 허용합니다.

업데이트 확인 및 업그레이드

Pi Agent는 최대 7일에 한 번 abcwyc/pi-agent-desktop의 최신 안정화 버전을 확인합니다:

• abcwyc/pi-agent-desktop
• earendil-works/pi
• agegr/pi-web

버전 관리 및 업그레이드 규칙은 다음과 같습니다:

1. 최신 안정 버전인 pi-agent-desktop 릴리스만 업데이트 알림에 사용되는 유일한 출처입니다.
2. 설정(Settings)의 업그레이드 버튼은 설치된 데스크톱 앱 버전이 더 오래되었을 때만 활성화됩니다.
3. 여러 구성 요소가 업데이트되어야 할 경우, 릴리스 자동화 시스템이 pi → pi-web → pi-agent-desktop 순서로 동기화하고 검증합니다.
4. 개별 JavaScript 패키지를 패치하는 것은 없습니다. 앱은 세 가지 구성 요소를 모두 최신 버전으로 포함하는 하나의 완전한 서명된 빌드를 다운로드합니다.
5. 설치 후 앱이 재시작되므로, 세 가지 구성 요소가 한 번에 동일하게 검증된 릴리스 상태로 적용됩니다.

이는 구성 요소들이 데스크톱 설치 환경에서 일관성을 유지하도록 하며, pi나 pi-web만 개별적으로 교체할 때 발생하는 런타임 비호환성 문제를 방지합니다.

새로운 상위 버전(upstream version)이 감지되었지만 이를 포함하는 서명된 pi-agent-desktop 릴리스가 아직 게시되지 않은 경우, 설정에서는 현재 설치 가능한 완전한 서명 빌드가 없다고 표시됩니다. 앱은 결코 서명되지 않은 파일을 다운로드하거나 의존성을 부분적으로 덮어쓰는 방식으로 되돌아가지 않습니다.

전체 동기화(sync), 서명 및 릴리스 구성에 대한 자세한 내용은 데스크톱 업데이트 및 릴리스를 참조하세요.

HTTP 프록시 (HTTP Proxy)

서버 측 모델 및 API 요청은 표준 환경 변수인 HTTP_PROXY, HTTPS_PROXY, 그리고 NO_PROXY를 따릅니다. 예를 들어, 터미널에서 개발 서버를 시작할 때 다음과 같습니다:

HTTP_PROXY=http://127.0.0.1:7890 \
HTTPS_PROXY=http://127.0.0.1:7890 \
NO_PROXY=localhost,127.0.0.1 \
...

로컬 개발 (Local Development)

요구 사항 (Requirements)

• macOS 11 이상 (Apple Silicon), Windows 10/11 x64, 또는 WebKitGTK 4.1 및 GTK 3가 설치된 Linux x64
• Node.js 22 (권장)
• npm
• Rust 1.85 이상
• macOS: Xcode Command Line Tools
• Windows: Microsoft C++ Build Tools 및 WebView2
• Linux: GTK/WebKitGTK 개발 패키지

웹 개발 서버 시작하기 (Start The Web Dev Server)

npm install
npm run dev

개발 서버는 http://localhost:30141에서 실행되며 브라우저를 열지 않습니다. npm run web은 동일한 루프백(loopback) 서버를 시작하고, 준비가 완료되면 데스크톱 브라우저의 http://127.0.0.1:30141을 엽니다. WSL 환경에서 실행할 경우 Windows 브라우저가 열립니다. Web 프로필을 참조하세요.

정상적인 개발 중에는 next build나 npm run build를 실행하지 마십시오. 이 명령어들은 .next/ 폴더에 파일을 작성하며, 이는 실행 중인 개발 서버를 방해할 수 있습니다. 프로덕션 빌드는 데스크톱 준비 스크립트 또는 CI(지속적 통합)에서 수행됩니다.

네트워크 노출 (LAN)

npm run dev와 npm start는 127.0.0.1에서만 리스닝합니다. 반면, npm run dev:lan, npm run start:lan, 그리고 pi-web -H 0.0.0.0은 모든 인터페이스에서 리스닝합니다. Pi Agent는 사용자와 마찬가지로 셸 명령(터미널 탭 및 에이전트 자체 도구)을 실행하고 파일을 읽을 수 있으므로, 포트에 접근할 수 있는 누구라도 동일한 접근 권한을 얻게 됩니다. LAN 모드를 사용하기 전에는 반드시 비밀번호를 설정하십시오:

PI_WEB_PASSWORD='choose-a-long-passphrase' npm run dev:lan

PI_WEB_PASSWORD가 설정되면, 브라우저는 첫 방문 시 비밀번호를 요청하며 실패한 시도는 속도 제한(throttled)됩니다. 연결 자체는 여전히 일반 HTTP이므로, 이를 HTTPS나 신뢰할 수 있는 VPN 뒤에 배치하고 PI_WEB_ALLOWED_HOSTS(쉼표로 구분된 값)를 사용하여 IP 주소가 아닌 DNS 이름을 허용하도록 설정하십시오. 런처는 비밀번호 없이 루프백 외부에서 리스닝하는 경우 경고 메시지를 출력합니다. 패키징된 데스크톱 앱은 영향을 받지 않습니다. 이는 루프백에 바인딩하고 프로세스별 토큰(per-process token)으로 WebView를 인증하기 때문입니다.

데스크톱 개발 모드 시작

npm run desktop:dev

이 명령어는 기존 Next.js 개발 서버를 시작하고, 설치 프로그램 없이 네이티브 Tauri 창에서 열어줍니다.

공통 확인 사항

# Node 테스트 (components/ tests를 포함하여 CI 동기 게이트와 동일)
npm test

...

release:verify는 GitHub에 접속하여 번들된 pi 및 pi-web이 최신 안정 버전과 정확히 일치하는지 확인하고, 컴포넌트 매니페스트를 실제 종속성(dependencies)과 비교 검사합니다.

데스크톱 패키징

npm run desktop:build

데스크톱 빌드:

1. 격리된 디렉터리에 Next.js 독립형(standalone) 서버를 생성합니다.
2. 현재 아키텍처용 Node.js 런타임을 번들링합니다.
3. 서버와 런타임을 앱 내의 Tauri 리소스로 배치합니다.
4. Apple Silicon Mac에서는 .app, .dmg, 및 업데이트어(updater) 아티팩트를, Windows x64에서는 NSIS -setup.exe 및 업데이트어 아티팩트를, Linux x64에서는 .deb 패키지를 생성합니다.

Linux의 경우, 이 패키지는 WebKitGTK 4.1 런타임과 GTK 3을 필요로 합니다. Node.js 런타임을 포함하고 있으므로 사용자가 별도로 Node.js를 설치할 필요가 없습니다.

로컬 빌드는 프로덕션 업데이트어를 등록하지 않으며 공식 업데이트를 수락할 수 없습니다. 공식 릴리스는 GitHub Actions를 통해 업데이트어 공개 키(public key)를 주입하고 일치하는 개인 키(private key)로 서명해야 합니다.

상위 저장소 동기화 및 릴리스 (Upstream Sync And Releases)

이 저장소에는 두 개의 연결된 자동화 워크플로우가 포함되어 있습니다:

• component-updates.yml: pi와 pi-web의 안정적인 릴리스를 매일 확인합니다. 새 버전이 나타나면, 먼저 들어오는 상위 변경 세트(upstream changeset)를 scripts/fork-ownership.json에 기록된

릴리스는 업데이트자 서명 파일(latest.json)과 모든 플랫폼의 컴포넌트 매니페스트가 업로드될 때까지 초안 상태로 유지됩니다. manifest 작업은 전체 빌드 매트릭스에 의존하므로, 어떤 플랫폼에서든 실패하면 게시되지 않습니다. 빌드 실패는 release-failure 이슈를 생성하거나 업데이트합니다.

업스트림 동기화(Upstream sync)는 Git 병합을 사용하므로, 이 포크의 Pi Agent 브랜딩, 설정 진입점, 그리고 업그레이드 로직은 로컬 수정 사항으로 남아 있습니다. 병합 충돌이 발생하면 워크플로우가 중단되는데, 이는 안전한 실패 모드입니다. 정말 위험한 경우는 충돌은 없지만 의미적으로 잘못된 병합입니다: 업스트림에서 이 포크가 변경했던 영역을 변경했고, Git이 이를 깨끗하게 병합했으며, 테스트는 여전히 통과합니다. 위의 경계 교차점은 정확히 그러한 경우를 위해 존재하며, 규칙은 Ownership boundaries에 있습니다.

동기화 실패는 component-sync-failure 이슈를 생성하거나 업데이트하므로, 아무것도 조용히 쌓이지 않습니다.

공식 릴리스에는 추가적으로 다음이 필요합니다:

• Tauri 업데이트자 키 쌍.
• 외부 사용자에게 배포하기 위한 Apple Developer ID 서명 및 노타라이징(notarization).
• Windows로 외부 사용자에게 배포할 경우 Authenticode 코드 서명이 권장됩니다. 서명되지 않은 .exe는 SmartScreen 경고를 유발할 수 있습니다.

프로젝트 구조

app/
  api/                  Next.js API: agent, sessions, models, files, update checks
components/             Pages, chat, sidebar, settings, and version notices
...

관련 문서