pi에서 플러그인처럼 쓰는 기능은 보통 pi package로 설치합니다. package 안에는 extension, skill, prompt template, theme가 들어갈 수 있습니다.
그래서 플러그인을 소개하기 전에 먼저 사용법부터 정리해야 합니다. 어떤 package가 유용한지 알아도, 설치와 확인 방법을 모르면 바로 쓸 수 없기 때문입니다.
이 글에서 할 것
pi install npm:...형식 이해하기- 전역 설치와 프로젝트 설치 구분하기
- 설치 후
/reload로 다시 읽기 - 설치된 package 목록 확인하기
- package 업데이트와 제거하기
.ts예제 파일과 npm package의 차이 구분하기
기본 설치 형식
npm에 배포된 pi package는 다음 형식으로 설치합니다.
pi install npm:패키지이름
예를 들어 resource center package를 설치하려면 이렇게 입력합니다.
pi install npm:pi-resource-center
설치가 끝난 뒤 pi가 이미 실행 중이라면 /reload를 실행합니다.
/reload
새 터미널에서 다시 pi를 실행해도 됩니다.
pi
GitHub package 설치
npm이 아니라 GitHub 저장소로 배포되는 package도 설치할 수 있습니다.
pi install git:github.com/user/repo@v1
예를 들어 특정 tag나 commit을 고정하고 싶을 때 유용합니다.
pi install git:github.com/user/[email protected]
버전을 고정하면 나중에 pi update를 실행해도 의도치 않게 최신 버전으로 움직이지 않습니다.
전역 설치와 프로젝트 설치
그냥 pi install을 쓰면 보통 사용자 전역 설정에 기록됩니다.
pi install npm:패키지이름
전역 설정 파일은 다음 위치입니다.
~/.pi/agent/settings.json
현재 프로젝트에서만 쓰고 싶다면 -l을 붙입니다.
pi install npm:패키지이름 -l
이 경우 프로젝트 설정에 기록됩니다.
.pi/settings.json
구분 기준은 간단합니다.
| 설치 범위 | 명령 | 언제 쓰나 |
|---|---|---|
| 전역 | pi install npm:패키지 |
모든 프로젝트에서 자주 쓰는 기능 |
| 프로젝트 | pi install npm:패키지 -l |
특정 repo에서만 필요한 기능 |
예를 들어 질문 UI나 resource browser는 전역으로 둘 만합니다. 반면 문서 파싱, 웹 조사, 사내 provider 연동은 프로젝트별로 둘 수도 있습니다.
설치 확인하기
설치된 package 목록은 다음 명령으로 확인합니다.
pi list
package가 명령을 제공한다면 pi 안에서 해당 slash command를 실행해 확인합니다.
예:
/resource
/ask-settings
/web-agent doctor
/docparser:doctor
명령이 동작하지 않으면 먼저 /reload를 실행합니다.
/reload
그래도 안 되면 pi list로 package가 실제로 설치되어 있는지 확인합니다.
업데이트하기
설치된 package와 pi를 함께 업데이트하려면 다음 명령을 사용합니다.
pi update
pi 본체만 업데이트하고 싶으면 다음 명령을 사용합니다.
pi update --self
package만 업데이트하고 싶으면 다음 명령을 사용할 수 있습니다.
pi update --extensions
특정 package만 업데이트할 수도 있습니다.
pi update npm:pi-resource-center
업데이트 후에는 실행 중인 pi에서 /reload하거나 새로 시작합니다.
제거하기
더 이상 쓰지 않는 package는 제거합니다.
pi remove npm:패키지이름
예:
pi remove npm:pi-resource-center
uninstall도 remove의 alias로 사용할 수 있습니다.
pi uninstall npm:pi-resource-center
package를 제거한 뒤에도 실행 중인 pi에는 이전 리소스가 남아 있을 수 있으므로 /reload하거나 pi를 재시작합니다.
.ts 파일과 package는 다르다
pi 공식 예제에는 이런 파일이 많이 나옵니다.
permission-gate.ts
protected-paths.ts
preset.ts
notify.ts
이것들은 npm package 이름이 아니라 extension 예제 파일입니다. 바로 설치하려면 보통 이런 식이 아닙니다.
pi install npm:permission-gate.ts
이런 명령은 일반적으로 맞지 않습니다.
실사용 순서는 이렇게 잡는 편이 좋습니다.
- 먼저 npm이나 GitHub로 배포된 pi package가 있는지 찾는다.
- 있으면
pi install npm:...또는pi install git:...로 설치한다. - package가 없고 예제 파일만 있다면 그때 직접
.pi/extensions/에 복사하거나 수정한다.
초보자나 일반 사용자는 1번과 2번만 알아도 충분합니다. .ts 파일 직접 복사는 커스터마이징 단계에서 다루는 것이 자연스럽습니다.
package를 찾는 방법
처음에는 pi-resource-center를 설치해 package와 리소스를 둘러보는 것이 가장 쉽습니다.
pi install npm:pi-resource-center
설치 후 pi 안에서 실행합니다.
/resource
리소스별로 열 수도 있습니다.
/resource packages
/resource extensions
/resource skills
/resource prompts
/resource themes
이 브라우저를 통해 현재 설치된 package, extension, skill을 확인하고 관리할 수 있습니다.
보안 체크리스트
pi package는 편하지만, extension은 사용자 시스템 권한으로 실행될 수 있습니다. 설치 전에는 최소한 아래를 확인합니다.
- package 이름과 GitHub 저장소가 신뢰할 만한가?
- README에 설치 명령과 사용 명령이 적혀 있는가?
- 파일을 읽거나 쓰는가?
- 셸 명령을 실행하는가?
- 네트워크 요청을 보내는가?
- API 키나 토큰을 로그에 남길 가능성이 있는가?
- 전역 설치가 필요한가, 프로젝트 설치가 더 안전한가?
가볍게 쓴다는 것은 아무 package도 안 쓰는 것이 아닙니다. 필요한 package는 쉽게 설치하되, 어디에 설치했고 어떤 권한을 갖는지 알고 쓰는 것입니다.
AI 코딩 도구와 함께 쓰는 프롬프트
Pi처럼 가벼운 에이전트 하네스를 쓸 때는 세션, 프로젝트 컨텍스트, package 설치 범위를 분명히 하는 것이 중요합니다. 중요: 네트워크 요청, sudo, 시스템 경로 접근이 필요한 package는 실행 전 별도 확인을 받으세요.
현재 프로젝트에서 pi를 실행해도 되는지 확인해줘.
프로젝트 폴더, AGENTS.md 같은 컨텍스트 파일, 현재 세션 목적을 먼저 설명하고 파일 수정은 하지 마.
이 pi package를 설치해도 되는지 검토해줘.
공식 출처, 설치 위치, 필요한 권한, 네트워크 요청 여부, 제거 방법을 먼저 설명하고, 설치 명령은 내가 허락하기 전에는 실행하지 마.
웹 탐색이나 고급 package를 붙일 때는 “민감 정보 접근 여부와 외부 요청이 발생하는지 먼저 알려줘”라고 덧붙이세요.
한 번에 정리
| 목적 | 명령 |
|---|---|
| npm package 설치 | pi install npm:패키지 |
| Git package 설치 | pi install git:github.com/user/repo@v1 |
| 프로젝트 전용 설치 | pi install npm:패키지 -l |
| 설치 목록 확인 | pi list |
| 전체 업데이트 | pi update |
| pi 본체 업데이트 | pi update --self |
| package 제거 | pi remove npm:패키지 |
| 리소스 다시 읽기 | /reload |
다음 글에서는 이 기본 사용법을 바탕으로, 설치해서 바로 쓸 수 있는 pi package들을 종류별로 살펴보겠습니다.
💬 댓글
이 글에 대한 의견을 남겨주세요