Pi는 터미널에서 실행되며 내 머신의 파일 위에서 일합니다. 동작하려면 지원되는 제공자(subscription, API 키, 로컬 모델 중 무엇이라도)를 통해 모델에 접근할 수 있어야 합니다. 이 글은 공식 퀵스타트를 따라 설치부터 첫 작업까지 네 단계로 정리합니다.

1단계: Pi 설치

macOS·Linux·Windows에서는 공식 설치 스크립트를 씁니다.

# macOS / Linux
curl -fsSL https://pi.dev/install.sh | sh

# Windows
powershell -c "irm https://pi.dev/install.ps1 | iex"

두 설치 스크립트는 모든 의존성을 고정(pin)하며, 이후 pi update로 갱신합니다. 대안으로 npm에서 직접 설치할 수도 있습니다. 이 방식은 과도(transitive) 의존성을 고정하지 않으며 Node.js 22.19 이상이 필요합니다.

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Nix를 쓰면 flake에서 최신 릴리스를 추가할 수 있습니다. Nix는 소스에서 빌드합니다.

nix profile add github:earendil-works/pi/stable

Nix로 설치한 경우 pi update가 아니라 nix profile upgrade pi로 갱신합니다. 특정 버전 고정은 github:earendil-works/pi/v1.0.0 같은 태그를 사용합니다. 설치는 다음 명령으로 확인합니다.

pi --version

2단계: Pi 시작

작업할 폴더로 이동해 pi를 실행합니다.

cd /path/to/folder
pi

작업 폴더는 관련 파일·지침·설정을 찾는 기준이 되고, 저장된 세션을 묶는 기준도 됩니다. 인터페이스는 대화 기록, 프롬프트·명령 입력 편집기, 현재 폴더·모델·세션 상태를 보여주는 하단바로 구성됩니다.

3단계: 모델 고르기

모델은 응답을 생성하는 대상이고, 제공자(provider)는 그 모델에 접근하게 해 주는 서비스나 계정입니다. Pi 안에서 /login을 실행하면 제공자를 고르고 subscription 연동이나 API 키 저장을 안내받습니다.

/login

연결 후 /model로 사용할 수 있는 다른 모델을 골라도 됩니다. 지원 제공자, 환경변수 인증, 로컬 모델, 호환 엔드포인트 설정은 설정 글에서 이어집니다.

4단계: 작업 시키기

Pi는 파일을 읽고 검색하고 명령을 실행하고 편집하는 모든 과정을 화면에 드러내지만, 매 도구 호출마다 승인 창을 띄우지는 않습니다. 업무에 맞는 작업을 넣어 봅니다.

@meeting-notes.md를 요약해서 액션 아이템을 action-items.md로 저장해 줘.

이 저장소가 어떻게 구성되어 있고 검사(check)를 어떻게 실행하는지 설명해 줘.

@previous.csv와 @current.csv를 비교해서 중요한 변경점을 요약해 줘.

편집기에서 @를 입력하면 전체 경로를 치지 않아도 파일 검색으로 추가할 수 있습니다. Pi가 끝내면 응답과 변경된 파일을 검토합니다. 중요한 작업은 버전 관리나 백업으로 보호하고, 신뢰할 수 없는 자료나 무인 자동화 작업에는 컨테이너 등 샌드박스를 쓰라는 것이 공식 안내입니다.

나중에 이어하기

Pi는 세션을 자동으로 저장합니다. 빠져나왔다가 같은 폴더에서 가장 최근 세션을 이어하려면 다음을 실행합니다.

pi --continue

다른 저장 세션을 고르려면 /resume을 사용합니다.

커스터마이징 수단 고르기

Pi를 바꾸고 싶을 때는 필요한 최소한의 수단부터 고르는 것이 공식 권장 순서입니다.

필요	시작점
폴더에 영구 지침 주기	AGENTS.md (컨텍스트 파일)
/ 메뉴에서 프롬프트 재사용	프롬프트 템플릿
작업별 지침과 보조 파일 추가	스킬
실행 가능한 도구·명령·이벤트 처리 추가	확장
터미널 컴포넌트 직접 만들기	TUI
지원되지 않는 모델 서비스 연결	커스텀 제공자
여러 자원을 한 단위로 설치·공유	Pi 패키지

각 수단은 이 주제의 메뉴얼 편에서 개별적으로 다룹니다.

삭제하기

npm으로 설치했다면 npm uninstall -g @earendil-works/pi-coding-agent, 설치 스크립트로 설치했다면 설치 스크립트를 다시 실행해 Uninstall Pi를 고르면 됩니다. Nix는 nix profile remove pi입니다. 어떤 방식이든 ~/.pi/agent/의 설정, 자격 증명, 세션, 설치된 Pi 패키지는 남아 있습니다.