[Pi 시리즈 6편] 설치해서 바로 쓰는 pi 패키지 2: 웹 탐색과 고급 운영

이전 글에서는 resource 관리, 질문 UI, 문서 파싱처럼 거의 모든 작업에서 바로 도움이 되는 package를 봤습니다.

이번 글에서는 웹 탐색 package인 @demigodmode/pi-web-agent를 먼저 살펴보고, 그다음 고급 extension을 어떤 기준으로 찾아 쓰면 좋을지 정리합니다.

---

이 글에서 할 것

• @demigodmode/pi-web-agent 설치하기
• /web-agent doctor로 동작 확인하기
• web_explore를 언제 쓰면 좋은지 보기
• 웹 탐색 결과 표시 방식 조정하기
• 고급 extension을 찾고 설치할 때의 기준 정리하기
• 전역 설치와 프로젝트 설치를 나누는 기준 확인하기

---

1. @demigodmode/pi-web-agent

설치

pi install npm:@demigodmode/pi-web-agent

설치 후 pi를 다시 시작하거나 /reload를 실행합니다.

/reload

이 package는 Pi 0.74 이상을 요구합니다. 오래된 pi를 쓰고 있다면 먼저 pi를 업데이트합니다.

pi update --self

설치 확인

pi 안에서 doctor 명령을 실행합니다.

/web-agent doctor

작업 메뉴를 열 수도 있습니다.

/web-agent

설정 화면은 다음 명령으로 엽니다.

/web-agent settings

사용

이 package는 web_explore라는 research tool을 제공합니다. 사용자는 보통 tool 호출 형식을 직접 쓰지 않고, 웹 조사가 필요하다는 요청을 자연어로 전달하면 됩니다.

예:

pi package gallery에서 최근 많이 쓰이는 package를 조사해서 설치 명령과 용도를 정리해줘.

더 명확하게 요청하고 싶다면 이렇게 말할 수 있습니다.

web_explore로 pi coding agent의 package 설치 문서를 조사하고 핵심 명령을 요약해줘.

web_explore는 검색, fetch, 필요한 경우 headless rendering, 출처 정리까지 하나의 bounded workflow 안에서 처리하도록 설계되어 있습니다. 모델에게 검색 도구, fetch 도구, 브라우저 도구를 따로 많이 노출하기보다, 조사 질문 하나를 던지는 구조에 가깝습니다.

언제 유용한가

• 공식 문서의 최신 내용을 확인해야 할 때
• npm package나 GitHub 저장소 정보를 비교해야 할 때
• 에러 메시지를 검색해야 할 때
• 블로그 글을 쓰기 전에 출처를 확인해야 할 때
• 단순 검색보다 근거와 caveat가 필요한 조사 작업

주의할 점도 있습니다. headless rendering fallback은 Chrome, Chromium, Edge, Brave 같은 Chromium 계열 브라우저가 필요할 수 있습니다. 브라우저가 없어도 검색과 일반 HTTP 읽기는 가능하지만, 렌더링이 필요한 페이지는 제한될 수 있습니다.

---

표시 방식 바꾸기

pi-web-agent는 결과 표시 방식을 조정할 수 있습니다.

/web-agent mode preview
/web-agent mode web_explore verbose
/web-agent mode web_explore inherit

현재 설정을 보려면 다음 명령을 사용합니다.

/web-agent show

대략 이렇게 고르면 됩니다.

모드	언제 쓰나
compact	빠르게 결론만 볼 때
preview	주요 근거를 함께 보고 싶을 때
verbose	블로그나 보고서 작성 전에 출처를 자세히 볼 때

---

2. 고급 extension은 package부터 찾는다

공식 예제에는 다음과 같은 고급 extension 파일이 많습니다.

permission-gate.ts
protected-paths.ts
git-checkpoint.ts
preset.ts
plan-mode/
ssh.ts
subagent/

하지만 이 이름들은 설치 명령이 아닙니다. 초보자에게는 .ts 파일을 복사하라는 설명보다, 먼저 설치 가능한 package가 있는지 찾는 흐름이 더 자연스럽습니다.

권장 순서는 다음과 같습니다.

1. /resource 또는 package gallery에서 원하는 기능의 package를 찾는다.
2. README에서 설치 명령을 확인한다.
3. pi install npm:... 또는 pi install git:...로 설치한다.
4. 설치 후 제공되는 slash command나 tool을 확인한다.
5. package가 없을 때만 공식 예제 .ts 파일을 참고해 직접 구성한다.

즉 고급 extension은 “직접 TypeScript를 만지는 기능”이라기보다, 먼저 package로 소비하고 필요할 때만 커스터마이징하는 쪽으로 접근하는 것이 좋습니다.

---

3. 어떤 종류의 고급 기능을 찾으면 좋을까

아직 package로 정리되지 않은 기능도 많지만, 어떤 종류의 확장을 찾으면 좋은지는 미리 알아둘 필요가 있습니다.

종류	원하는 기능
안전장치	위험한 bash 명령 확인, 보호 경로 설정
Git 복구	turn 단위 checkpoint, 자동 commit, 세션 bookmark
컨텍스트 관리	custom compaction, 자동 compact trigger, handoff
워크플로우	preset, tools on/off, plan mode, TODO 관리
UI/알림	notify, status line, model status, custom footer
외부 연동	GitHub issue, SSH, custom provider, subagent

이 목록은 “당장 이 이름으로 설치하라”는 의미가 아닙니다. package를 찾을 때 어떤 키워드로 찾으면 좋은지 알려주는 지도에 가깝습니다.

예를 들어 위험 명령 확인 기능을 원한다면 package 검색에서 permission, guard, safe, protected 같은 단어를 찾으면 됩니다. 웹 조사가 필요하면 web, search, research를 찾습니다. 문서 처리가 필요하면 doc, pdf, ocr 같은 단어가 단서가 됩니다.

---

4. 전역 설치와 프로젝트 설치 기준

웹 탐색이나 문서 파싱 같은 기능은 편하지만, 모든 프로젝트에서 항상 필요한 것은 아닙니다. 설치 범위를 나누는 기준을 정해두면 pi를 계속 가볍게 유지할 수 있습니다.

전역 설치 후보:

pi install npm:pi-resource-center
pi install npm:@eko24ive/pi-ask

프로젝트 설치 후보:

pi install npm:@demigodmode/pi-web-agent -l
pi install npm:pi-docparser -l

기준은 이렇게 잡을 수 있습니다.

질문	전역 설치	프로젝트 설치
모든 프로젝트에서 쓰나?	예	아니오
네트워크 접근이 필요한가?	신중히	프로젝트별 권장
문서/이미지 처리가 필요한가?	자주 쓰면	특정 프로젝트만
팀과 공유해야 하나?	개인 도구면 전역	팀 표준이면 프로젝트

---

5. 내가 추천하는 시작 조합

처음에는 이 정도 조합이면 충분합니다.

pi install npm:pi-resource-center
pi install npm:@eko24ive/pi-ask

웹 조사가 필요하면 추가합니다.

pi install npm:@demigodmode/pi-web-agent

문서 파싱이 필요하면 추가합니다.

pi install npm:pi-docparser

설치 후 확인 명령은 다음과 같습니다.

/resource
/ask-settings
/web-agent doctor
/docparser:doctor

이 네 개를 모두 전역으로 설치해도 되지만, 프로젝트별로 엄격하게 나누고 싶다면 pi-web-agent와 pi-docparser는 -l로 설치하는 것도 좋은 선택입니다.

---

보안 체크리스트

웹 탐색, 문서 파싱, SSH, custom provider 계열은 권한과 네트워크 범위가 넓어질 수 있습니다. package 설치 전에는 아래를 확인합니다.

• README에 설치 명령과 사용 명령이 명확한가?
• 어떤 tool이나 slash command를 추가하는가?
• 네트워크 요청을 보내는가?
• 로컬 파일을 읽거나 쓰는가?
• 외부 브라우저나 host dependency가 필요한가?
• API key, token, cookie를 다루는가?
• 전역 설치보다 프로젝트 설치가 안전하지 않은가?

필요한 기능을 쓰는 것은 좋습니다. 다만 package가 어떤 권한을 갖는지 모른 채 항상 켜두는 것은 피해야 합니다.

---

AI 코딩 도구와 함께 쓰는 프롬프트

Pi처럼 가벼운 에이전트 하네스를 쓸 때는 세션, 프로젝트 컨텍스트, package 설치 범위를 분명히 하는 것이 중요합니다. 중요: 네트워크 요청, sudo, 시스템 경로 접근이 필요한 package는 실행 전 별도 확인을 받으세요.

현재 프로젝트에서 pi를 실행해도 되는지 확인해줘.
프로젝트 폴더, AGENTS.md 같은 컨텍스트 파일, 현재 세션 목적을 먼저 설명하고 파일 수정은 하지 마.

이 pi package를 설치해도 되는지 검토해줘.
공식 출처, 설치 위치, 필요한 권한, 네트워크 요청 여부, 제거 방법을 먼저 설명하고, 설치 명령은 내가 허락하기 전에는 실행하지 마.

웹 탐색이나 고급 package를 붙일 때는 “민감 정보 접근 여부와 외부 요청이 발생하는지 먼저 알려줘”라고 덧붙이세요.

한 번에 정리

목적	설치	확인/사용
웹 조사	pi install npm:@demigodmode/pi-web-agent	/web-agent doctor
package 탐색	pi install npm:pi-resource-center	/resource
구조화 질문	pi install npm:@eko24ive/pi-ask	/ask-settings, /answer
문서 파싱	pi install npm:pi-docparser	/docparser:doctor
프로젝트 전용 설치	pi install npm:패키지 -l	.pi/settings.json

pi를 가볍게 쓴다는 것은 package를 안 쓰는 것이 아닙니다. 필요한 package는 쉽게 설치하고, 설치 범위와 권한을 의식하면서 작업에 맞는 조합을 만드는 것입니다.