Pi 에이전트 입문 가이드: 설치부터 첫 번째 작업까지

소개

Pi를 처음 실행하면 거의 지루해 보일 정도로 단순합니다. 트랜스크립트(실행 기록), 한 줄짜리 에디터, 그리고 폴더·모델·세션 정보가 적힌 푸터가 전부입니다. 화려한 대시보드도, 친절한 온보딩 마법사도 없습니다.

하지만 이런 미니멀리즘이야말로 핵심입니다. Pi는 거대한 플랫폼이 아니라 ‘하네스(harness)’입니다. 핵심 루프는 사용자 → 활성 브랜치 + 도구 → 모델 → 도구 호출 → 결과로 이어집니다. 실제 작업 폴더에서 이 루프가 한 번 돌아가는 모습을 보고 나면, 이후의 모든 고급 기능이 왜 그 자리에 있는지 자연스럽게 이해할 수 있습니다.

이 가이드에서는 약 10분 만에 아무것도 없는 상태에서 첫 번째 실제 작업을 완료해 봅니다. 설치, 작업 폴더 선택, 모델 연결, 명확한 범위의 단일 작업 실행, 그리고 저를 포함한 입문자들이 흔히 저지르는 5가지 실수를 피하는 방법까지 살펴봅니다. 확장 기능(extension), MCP, 코드모드(codemode) 같은 복잡한 개념은 오늘 다루지 않습니다.

Pi 시작하기란 무엇인가

Pi를 시작한다는 것은 오직 다음 세 가지만을 뜻합니다:

Pi 설치 및 정상 작동 확인 (pi --version)
올바른 작업 폴더에서 Pi 실행 (cd /path/to/folder && pi): 해당 폴더의 AGENTS.md, .pi/ 설정, 세션 그룹을 올바르게 인식하도록 합니다.
모델 연결(/login → /model) 및 작은 단일 작업 완료: 트랜스크립트에서 read(읽기) → run(실행) → edit(수정)으로 이어지는 전체 한 턴을 직접 확인합니다.

Git을 처음 배울 때를 떠올려 보세요. 먼저 init, add, commit부터 익히고 복잡한 브랜치 전략은 나중에 배우는 것과 같습니다.

Pi 시작하는 방법

1단계: Pi 설치하기 (한 가지 방법 선택)

인스톨러 (권장, macOS/Linux): 모든 의존성을 고정하며, pi update로 간편하게 업데이트합니다.

curl -fsSL https://pi.dev/install.sh | sh
pi --version
# 1.0.4 — 이 가이드를 테스트한 버전입니다

npm: Node.js 22.19 이상이 필요합니다. 전이 의존성(transitive dependencies) 버전은 고정되지 않습니다.

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

Nix: 소스 코드에서 직접 빌드합니다.

nix profile add github:earendil-works/pi/stable
# 업데이트: nix profile upgrade pi (이 환경에서는 pi update가 작동하지 않습니다)

나중에 삭제하려면 인스톨러를 다시 실행해 Uninstall을 선택하거나, npm uninstall -g, 또는 nix profile remove pi를 실행하세요. ~/.pi/agent/에 저장된 설정과 세션은 삭제 후에도 유지되며, 이는 의도된 동작입니다.

2단계: 올바른 작업 폴더에서 시작하기

cd /path/to/folder
pi

실행 시 화면 동작: 프로젝트 리소스를 로드하기 전에 Pi가 이 폴더를 신뢰할 것인지 물어볼 수 있습니다. .pi/ 폴더의 내용을 신뢰할 수 있을 때만 승인하세요. 승인하면 다음 화면이 나타납니다:

트랜스크립트 (중앙): 프롬프트, 모델 응답, 도구 호출, 실행 결과, 에러 출력
에디터 (하단): 메시지를 입력하는 공간입니다. Enter로 전송하고, Shift+Enter로 줄바꿈하며, 프롬프트가 길면 Ctrl+G로 외부 에디터를 열 수 있습니다.
푸터 (최하단): 현재 폴더, 세션, 모델, 컨텍스트 사용량, 비용 표시

헤더에는 어떤 지침이나 리소스가 로드되었는지 표시됩니다. 한 번 가볍게 확인해 보세요. 아무것도 로드되지 않았다고 나온다면 현재 폴더에 AGENTS.md가 없다는 뜻입니다.

팁: 빈 폴더 대신 파일이 몇 개 들어 있는 실제 프로젝트 폴더에서 시작하세요. Pi가 제 가치를 보여주려면 읽을 대상이 있어야 합니다.

3단계: /login 명령어로 모델 연결하기

모델은 답변을 생성하고, 프로바이더(제공자)는 모델에 접근하기 위한 계정이나 서비스(구독, API 키, 로컬 모델)를 의미합니다.

Pi 내부에서 다음을 입력합니다:

/login

프로바이더를 선택하고 안내를 따릅니다(구독 OAuth 로그인 또는 API 키 입력). 완료되면 모델을 선택합니다:

/model

사용할 모델을 선택합니다. (Ctrl+L을 누르면 동일한 모델 선택 창이 열립니다. 지원되는 모델에서는 /thinking 또는 Shift+Tab으로 추론 수준을 조절할 수 있습니다. /logout으로 연결을 해제합니다.)

환경 변수(ENV) 인증과 로컬 모델도 지원하지만, 처음부터 그렇게 시작하지는 마세요. 대화형 로그인이 정상 작동하는지 먼저 확인해 두어야 나중에 문제가 생겼을 때 인증 때문이 아니라는 것을 바로 알 수 있습니다.

4단계: 명확한 범위의 단일 작업 실행해보기

아래 예시 중 하나를 복사해 붙여넣어 보세요. 파일 전체 경로를 일일이 입력하지 말고 @를 입력해 퍼지 검색으로 파일을 찾고, Tab 키로 완성하세요.

Summarize @meeting-notes.md and save the action items to action-items.md.

Explain how this repository is structured and how to run its checks.

Compare @previous.csv with @current.csv and summarize the important changes.

단계별로 화면에 나타나는 과정:

Pi가 @파일명을 실제 메시지 내용으로 확장합니다 (프롬프트 템플릿 확장).
모델이 파일 읽기를 요청합니다. 각 read 호출과 파일 발췌 내용이 표시됩니다.
주변 맥락을 파악하기 위해 bash 검색(rg, ls)을 수행할 수도 있습니다.
결과물 작성이 필요하다면 edit 또는 write를 실행합니다.
무엇이 바뀌었는지 요약하는 최종 응답을 출력합니다.

Pi는 매 도구 호출마다 사용자에게 일일이 확인을 구하지 않습니다. Ctrl+O를 눌러 도구 출력 결과를 펼치거나 접을 수 있고, Ctrl+T로 사고 과정(thinking) 블록을 보거나 숨길 수 있습니다. 지금부터 좋은 습관을 들이는 것이 좋습니다. 최종 텍스트만 읽지 말고 도구 호출 과정을 직접 확인하세요. 중요한 작업에는 버전 관리나 백업을 활용하고, 신뢰할 수 없는 저장소라면 컨테이너 환경에서 실행하세요.

작업이 진행 중일 때도 방향을 제어할 수 있습니다. 텍스트를 입력하고 Enter를 누르면 현재 작업을 조정할 수 있고, Alt+Enter를 누르면 현재 작업 완료 후 이어질 후속 메시지를 대기열에 추가할 수 있으며, Esc를 누르면 작업을 중단합니다(대기 중이던 메시지는 에디터로 돌아옵니다).

5단계: 세션 저장, 재개, 이름 지정하기

Pi는 세션을 자동으로 저장합니다.

/name my-first-pi-task
/session

/session은 세션 파일 경로, ID, 메시지/토큰 수, 비용을 보여줍니다. Ctrl+C나 exit으로 종료한 뒤, 다음과 같이 돌아올 수 있습니다:

pi --continue
# 동일한 폴더 → 가장 최근 세션 재개; /resume으로 다른 세션 선택; /new로 새 세션 시작

지금 한번 테스트해 보세요. Pi를 종료한 다음 pi --continue로 다시 열어, 방금 만든 action-items 파일이 여전히 컨텍스트에 남아 있는지 확인해 보세요. 이러한 연속성 덕분에 며칠에 걸친 작업에서도 Pi를 끊김 없이 활용할 수 있습니다. 세부적인 브랜치 모델은 다음 글에서 다룹니다.

흔한 5가지 실수와 해결법

~(홈 디렉토리)나 /(루트)에서 실행하기
- 증상: Pi가 엉뚱한 컨텍스트를 로드하고, 모든 세션이 한 그룹으로 쌓입니다.
- 해결법: pi를 실행하기 전에 반드시 프로젝트 폴더로 cd 이동하세요. 작업 폴더는 단순한 위치가 아니라 필수 매개변수입니다.
처음부터 “전체 리팩터링해줘”라고 요청하기
- 증상: 실행 시간이 너무 길어지고, 변경 사항(diff)이 방대해 무엇이 맞는지 확인할 수 없습니다.
- 해결법: 첫 작업은 읽기 전용 작업에 쓰기 1건 정도로 작게 잡으세요(앞서 살펴본 회의록 요약 예시처럼). 도구 호출 50개를 맹신하기 전에, 먼저 5개의 호출을 검토하는 법부터 익히세요.
/login 후 /model 선택을 건너뛰기
- 증상: “Pi가 똑똑하지 못한 것 같다”고 느껴집니다. 기본 설정인 소형 모델로 실행 중일 가능성이 높습니다.
- 해결법: /model을 명시적으로 실행하고 하단 푸터를 확인하세요. 모델 선택이 프롬프트 기교보다 품질을 훨씬 크게 좌우합니다.
@를 쓰지 않고 전체 경로를 직접 붙여넣기
- 증상: 오타가 나거나 파일을 찾지 못합니다.
- 해결법: @ 입력 후 퍼지 검색을 사용하고 Tab으로 완성하세요. 훨씬 빠를 뿐만 아니라 Pi가 메시지 컨텍스트에 경로를 정확하게 반영합니다.
도구 호출을 단순 소음으로 취급하기
- 증상: 최종 답변만 읽다가, 결과를 오염시킨 엉뚱한 bash 명령어를 놓치게 됩니다.
- 해결법: 초기 작업에서는 Ctrl+O를 눌러 도구 호출을 열어두세요. 트랜스크립트는 단순한 로그가 아니라 결과물을 검토하는 공간이며, 문제 발생을 막는 첫 번째 방어선입니다.

실전 활용 예시

루프는 같지만 세 가지 서로 다른 형태입니다. 모두 결과 검증이 쉬운 파일 단위로 범위가 제한되어 있다는 점에 주목하세요:

회의록에서 액션 아이템 추출: Summarize @meeting-notes.md and save the action items to action-items.md.
30초 안에 결과를 검증할 수 있습니다. 생성된 파일을 열어보세요. 담당자를 엉뚱하게 지어내지 않았나요? 이것이 모델 품질을 확인하는 기준입니다.
저장소 파악: Explain how this repository is structured and how to run its checks.
read + bash + AGENTS.md 자동 감지 기능을 테스트하기에 좋습니다. 필자는 낯선 저장소에서 코드를 수정하기 전에 항상 이 명령부터 실행합니다.
터미널 단축 실행: !git status는 명령을 실행하고 그 결과를 컨텍스트에 포함합니다. 반면 !!git log --oneline -5는 모델에 전달하지 않고 터미널에서만 실행합니다. Pi에게 결과를 보여주고 싶을 때는 !, 나만 확인하고 싶을 때는 !!를 사용하세요.

추가 참고 자료

공식 문서 (아래 순서대로 읽는 것을 권장합니다):

빠른 시작 (Quickstart) — 설치/시작/모델/작업 실행 및 사용자 설정 선택 가이드표 (AGENTS.md → 프롬프트 → 스킬 → 확장 기능 → 패키지)
터미널에서 Pi 사용하기 — ! 명령어, /copy /export /share, /settings, /debug → pi-debug.log (프롬프트, 파일 내용, 인증 정보가 포함될 수 있으므로 공유 전 정리 필수)
모델 및 프로바이더 선택하기 — 구독, API 키, 로컬 모델, 커스텀 엔드포인트

이 시리즈의 다른 글:

이론적 배경: 하네스 엔지니어링: 왜 모델이 아니라 하네스가 핵심 제품인가

정리

이제 입문자에게 필요한 세 가지가 모두 준비되었습니다. 설치된 Pi, 신뢰할 수 있는 프로젝트 폴더, 작동하는 모델, 그리고 직접 검증해 본 한 번의 루프 경험입니다. 이후의 모든 고급 기능은 이 기본 루프를 확장하는 것에 불과합니다.

오늘 당장 여러분이 관심 있는 실제 파일로 한 가지 작업을 실행해 보세요. 내일은 작업이 의도와 다르게 흘러갈 때 브랜치를 나누는 방법을 배우면 됩니다.

피드백 및 다음 단계

진행하다 막히셨나요? 댓글에 OS, 설치 방법, pi --version, 그리고 실패한 단계(설치 / 폴더 신뢰 확인 / /login / 첫 작업)를 남겨주세요.

소개