이전 글에서는 왜 무거워진 코딩 에이전트 대신 pi를 살펴보게 되었는지 정리했습니다. 이번 글에서는 실제로 pi를 설치하고 첫 세션을 열어보겠습니다.
목표는 거창하지 않습니다. 설치하고, 모델을 연결하고, 프로젝트 폴더에서 pi에게 첫 요청을 보내는 것까지입니다.
이 글에서 할 것
- npm으로 pi 설치하기
- 로그인 또는 API 키로 모델 연결하기
- 프로젝트 폴더에서 pi 실행하기
- 파일 참조와 셸 명령 실행 방식 익히기
- 처음 알아두면 좋은 인터랙티브 명령 확인하기
시작하기 전에 확인할 것
필요한 것은 많지 않습니다.
- Node.js와 npm
- 터미널 앱
- 사용할 LLM provider 계정 또는 API 키
- pi를 실행해볼 프로젝트 폴더
macOS에서 Node.js가 없다면 Homebrew로 설치할 수 있습니다.
brew install node
이미 설치되어 있다면 버전만 확인해도 됩니다.
node --version
npm --version
버전 번호가 보이면 준비가 된 것입니다.
Step 1: pi 설치하기
pi는 npm으로 설치할 수 있습니다. 공식 문서의 기본 설치 명령은 다음과 같습니다.
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
--ignore-scripts는 npm 패키지 설치 중 실행되는 lifecycle script를 막는 옵션입니다. 원하지 않는 설치 스크립트 실행을 줄여 더 통제된 방식으로 설치하려는 목적이 큽니다. pi는 일반적인 npm 설치에서 install script에 의존하지 않기 때문에 이 옵션을 붙여 설치할 수 있습니다.
설치가 끝났다면 버전을 확인합니다.
pi --version
버전 번호가 나오면 설치가 정상적으로 끝난 것입니다.
Step 2: 설치 스크립트 방식도 있다
npm 대신 설치 스크립트를 사용할 수도 있습니다.
curl -fsSL https://pi.dev/install.sh | sh
다만 curl | sh 방식은 원격 스크립트를 바로 실행합니다. 내용을 확인했거나 신뢰하는 환경에서만 사용하는 것이 좋습니다. 처음 설치라면 npm 방식이 더 명시적입니다.
Step 3: 모델 연결하기
pi를 쓰려면 사용할 모델 provider를 연결해야 합니다. 방법은 크게 두 가지입니다.
첫 번째는 API 키를 환경 변수로 넣는 방식입니다. 예를 들어 Anthropic API 키를 쓴다면 다음처럼 실행합니다.
export ANTHROPIC_API_KEY=sk-ant-...
pi
두 번째는 기존 구독 계정으로 로그인하는 방식입니다. pi를 실행한 뒤 /login을 입력합니다.
pi
/login
공식 문서 기준으로 pi는 Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot 같은 구독 로그인도 지원합니다. API 키 방식으로는 Anthropic, OpenAI, Google Gemini, OpenRouter, Amazon Bedrock 등 여러 provider를 사용할 수 있습니다.
처음에는 이미 갖고 있는 구독이나 API 키 하나만 연결하면 충분합니다. 여러 모델을 한 번에 정리하려고 하면 시작이 오히려 무거워집니다.
Step 4: 프로젝트 폴더에서 실행하기
이제 pi를 사용할 프로젝트 폴더로 이동합니다.
cd ~/my-project
pi
실행 후에는 일반 채팅처럼 요청하면 됩니다.
이 프로젝트의 구조를 간단히 읽고, 어떤 폴더가 핵심인지 설명해줘.
처음 요청은 너무 큰 작업보다 가벼운 탐색이 좋습니다. 예를 들어 “전체 리팩터링해줘”보다 “프로젝트 구조를 먼저 설명해줘”가 안전합니다.
Step 5: 파일을 직접 참조하기
pi의 편한 점 중 하나는 @로 파일을 참조할 수 있다는 것입니다. 에디터에서 @를 입력하면 프로젝트 파일을 fuzzy-search로 찾을 수 있습니다.
예를 들어 특정 파일의 역할을 물어볼 수 있습니다.
@src/lib/content/posts.server.ts 이 파일이 마크다운 글을 어떻게 로딩하는지 설명해줘.
파일을 명시하면 모델이 엉뚱한 파일을 추측할 가능성이 줄어듭니다. 특히 큰 프로젝트에서는 “어딘가에 있는 로더를 찾아줘”보다 “이 파일을 먼저 읽어줘”가 더 빠르고 안정적입니다.
Step 6: 셸 명령 실행하기
터미널 명령을 실행하고 그 결과를 모델에게 전달하고 싶으면 !를 붙입니다.
!npm run check
이렇게 하면 명령 실행 결과가 대화에 포함됩니다. 모델은 실패 로그를 보고 다음 수정 방향을 제안할 수 있습니다.
반대로 명령은 실행하되 결과를 모델에게 보내고 싶지 않을 때는 !!를 사용할 수 있습니다.
!!git status --short
처음에는 !npm run check, !git status --short, !ls 정도만 써도 충분합니다.
Step 7: 여러 줄 요청하기
긴 요청을 쓸 때는 Shift+Enter로 줄바꿈할 수 있습니다.
다음 기준으로 이 글을 검토해줘.
1. 초보자가 이해하기 어려운 용어가 있는지
2. 앞뒤 문단 연결이 자연스러운지
3. 명령어 설명이 충분한지
짧은 명령을 여러 번 던지는 것도 좋지만, 검토 기준이 있을 때는 이렇게 한 번에 정리해서 주는 편이 더 안정적입니다.
자주 쓰는 인터랙티브 명령
pi에서는 /를 입력해 명령을 실행합니다. 처음에는 모든 명령을 외울 필요가 없습니다. 아래 정도만 알아두면 충분합니다.
| 명령 | 용도 |
|---|---|
/login |
provider 로그인 |
/model |
사용할 모델 변경 |
/settings |
thinking level, theme, message delivery 등 설정 변경 |
/resume |
이전 세션 선택 |
/new |
새 세션 시작 |
/session |
현재 세션 정보 확인 |
/hotkeys |
단축키 목록 보기 |
/quit |
종료 |
모델 선택은 /model로 할 수 있고, 단축키로는 Ctrl+L을 사용할 수 있습니다.
여러 모델을 번갈아 쓰는 사람이라면 /scoped-models도 살펴볼 만합니다. 이 명령은 Ctrl+P로 순환할 모델 목록을 켜고 끄는 데 사용합니다.
AI 코딩 도구와 함께 쓰는 프롬프트
Pi처럼 가벼운 에이전트 하네스를 쓸 때는 세션, 프로젝트 컨텍스트, package 설치 범위를 분명히 하는 것이 중요합니다. 중요: 네트워크 요청, sudo, 시스템 경로 접근이 필요한 package는 실행 전 별도 확인을 받으세요.
현재 프로젝트에서 pi를 실행해도 되는지 확인해줘.
프로젝트 폴더, AGENTS.md 같은 컨텍스트 파일, 현재 세션 목적을 먼저 설명하고 파일 수정은 하지 마.
이 pi package를 설치해도 되는지 검토해줘.
공식 출처, 설치 위치, 필요한 권한, 네트워크 요청 여부, 제거 방법을 먼저 설명하고, 설치 명령은 내가 허락하기 전에는 실행하지 마.
웹 탐색이나 고급 package를 붙일 때는 “민감 정보 접근 여부와 외부 요청이 발생하는지 먼저 알려줘”라고 덧붙이세요.
한 번에 정리
| 단계 | 할 일 |
|---|---|
| 1 | npm install -g --ignore-scripts @earendil-works/pi-coding-agent로 설치 |
| 2 | pi --version으로 설치 확인 |
| 3 | API 키 또는 /login으로 provider 연결 |
| 4 | 프로젝트 폴더에서 pi 실행 |
| 5 | @파일경로로 파일 참조 |
| 6 | !명령어로 실행 결과를 모델에게 전달 |
다음 글에서는 세션, 컨텍스트 파일, AGENTS.md, /tree, /fork, /compact처럼 pi를 오래 쓰기 위해 필요한 관리 기능을 다룹니다.
💬 댓글
이 글에 대한 의견을 남겨주세요