11.2만 개 스타 받은 AI 에이전트 툴킷 Pi, 내 워크플로우에 맞춰 쓰는 법
기존 AI 코딩 도구는 정해진 방식대로 써야 해서 내 워크플로우에 맞추기 어려웠습니다. Pi는 확장·기술·프롬프트 템플릿·테마를 조합해 나만의 에이전트를 만들고 npm이나 git으로 공유할 수 있게 해줍니다. 이 자료는 Pi의 핵심 개념부터 설치, 인터랙티브·CLI·RPC·SDK 4가지 실행 모드, 실전 커스터마이징 포인트까지 한눈에 정리합니다.
AI 코딩 에이전트를 도입하려는데 '우리 팀 방식대로 못 고친다'는 벽에 부딪힌 적 있으신가요? 11.2만 개 스타를 받은 Pi는 '도구에 나를 맞추는 게 아니라, 도구를 나에게 맞춘다'는 철학으로 만든 최소한의 에이전트 하네스입니다. 이번 글에서는 Pi가 무엇인지, 왜 쓰는 설치부터 4가지 실행 모드, 실무 커스터마이징 포인트까지 현업 관점에서 정리했습니다.
Pi, 도대체 무엇인가요?
깃허브에서 11.2만 개의 스타를 받으며 개발자들의 주목을 받는 오픈소스 도구가 있어요. 바로 earendil-works/pi 저장소의 Pi예요. 1년 2개월 전(2025년 8월)에 처음 만들어진 이후 이번 달(2026년 10월)까지 활발하게 업데이트를 이어오고 있는데요. 주 언어로 TypeScript를 사용하며, 자유롭게 활용할 수 있는 MIT 라이선스로 공개되어 있어요.
Pi는 스스로를 '사용자가 온전히 자신만의 것으로 만들 수 있는 최소한의 확장형 에이전트 하네스(minimal, extensible agent harness)'로 정의해요. 사람이 도구의 방식에 억지로 맞추는 것이 아니라, 나의 워크플로우에 Pi를 맞추는 것이 핵심 철학이에요. 복잡하게 얽힌 하위 에이전트나 계획 모드 같은 기능을 덜어내고, 필요한 요소는 사용자가 직접 구현하거나 패키지로 붙여 쓸 수 있게 설계되었어요.
Pi가 제공하는 기본 도구 상자에는 AI 에이전트를 안정적으로 구축하고 실행하는 데 꼭 필요한 4가지 핵심 요소가 포함되어 있어요.
| 핵심 요소 | 역할 및 특징 |
|---|---|
| 통합 LLM API (unified LLM API) | 다양한 모델과 공급자를 일관된 인터페이스로 제어 |
| 에이전트 루프 (agent loop) | 작업을 순차적으로 판단하고 자율적으로 수행하는 실행 루프 |
| TUI | 터미널 환경에서 직관적으로 상호작용할 수 있는 텍스트 사용자 인터페이스 |
| 코딩 에이전트 CLI (coding agent CLI) | 작업 디렉터리에서 바로 구동해 실무 코딩 작업을 맡기는 커맨드라인 도구 |
이렇게 준비된 기본기를 바탕으로 대화형 실행뿐만 아니라 출력 모드나 JSON 모드를 통한 자동화, RPC 원격 제어, 그리고 Pi TypeScript SDK를 통한 애플리케이션 구축까지 폭넓게 확장해 활용할 수 있어요.
왜 기존 도구 대신 Pi를 쓰나요?
Pi는 최소한의 코어만 제공하고, 서브 에이전트나 플랜 모드 같은 복잡한 기능을 의도적으로 빼서 설계됐어요. 그래서 불필요한 옵션에 신경 쓸 필요 없이, 바로 LLM API와 에이전트 루프만으로 작업을 시작할 수 있답니다. 기존 도구들은 기본적으로 다양한 워크플로우를 지원하려다 보니 설정이 복잡하고, 내게 맞지 않는 기능이 많이 포함돼 있죠. Pi는 ‘내 워크플로우에 맞춰 쓰는’ 것이 목표라, 필요한 부분만 선택해 조립할 수 있어요.
또한 Pi는 확장·스킬·프롬프트 템플릿·테마·패키지 시스템을 통해 완전한 맞춤형 에이전트를 만들 수 있어요. 예를 들어 extensions 로 새로운 명령을 추가하고, skills 로 도메인 특화 로직을 구현하며, prompt templates 로 반복 프롬프트를 재사용할 수 있죠. 만든 조각들을 Pi packages 로 묶어 npm이나 git에 배포하면 팀 전체가 동일한 에이전트를 바로 쓸 수 있습니다. 이렇게 조립식으로 구성하면 기존 도구에서 제공하는 불필요한 기능을 피하면서도, 필요할 때는 원하는 기능을 바로 설치해 확장할 수 있어요.
pi update- Extensions 로 기능 추가
- Skills 로 도메인 로직 구현
- Prompt templates 로 프롬프트 재사용
- Themes 로 UI 맞춤
- Pi packages 로 npm·git 배포
| ⭐ 스타 | 11.2만 개 |
|---|---|
| 🍴 포크 | 14,176개 |
| 🕒 마지막 업데이트 | 이번 달(2026년 10월) |
설치부터 첫 실행까지 3단계
Pi를 내 컴퓨터에 올리는 건 딱 세 단계면 충분해요. 먼저 Node.js 22.19 이상이 깔려 있는지 확인하세요. macOS·Linux·Windows 공식 인스톨러가 이 버전을 자동으로 넣어주니 따로 버전 관리에 신경 쓸 필요는 없어요.
1️⃣ 공식 인스톨러(또는 npm)로 설치
윈도우라면 다운로드 페이지에서
.exe를 받아 실행하면 되고, macOS·Linux 터미널에선curl -fsSL https://pi.dev/install.sh | sh한 줄이면 끝납니다. npm을 쓰고 싶다면npm i -g @earendil/pi로 설치하되, 이 방식은 의존성 핀닝이 되지 않아pi update로 자동 업데이트를 못 받아요.2️⃣ 자동 업데이트 핀닝 켜기
공식 인스톨러로 설치했다면 이미
pi update명령이 의존성까지 고정해둔 상태로 대기 중이에요. 새 버전이 나오면 이 명령 한 번만 치면 최신 빌드로 갈아탑니다.3️⃣ 작업 폴더에서
pi실행 →/login으로 프로바이더 연동프로젝트 루트에서
pi를 치면 TUI가 뜨고, 내부 명령/login을 입력해 구독 또는 API 키를 연결하면 바로 작업을 던질 수 있습니다.
pi
/login여기까지 마치면 Pi가 내 워크플로우 디렉터리에서 대기 상태가 됩니다. 이제 스킬·확장·프롬프트 템플릿을 골라 나만의 에이전트로 키워보세요.
한눈에 보는 4가지 실행 모드
Pi는 워크플로우에 맞춰 4가지 실행 모드를 고를 수 있어요. 용도와 진입 명령어를 표로 정리했어요.
| 모드 | 용도 | 진입 명령어(예시) | 비고 |
|---|---|---|---|
| 인터랙티브 TUI | 직접 대화를 나누며 작업을 확인하고 싶을 때 | pi | 기본 실행, TUI 진입 |
| 자동화용 Print/JSON CLI | 스크립트·CI/CD 파이프라인에 결과를 바로 넘길 때 | pi --print "작업 내용" 또는 pi --json "작업 내용" | 출력 형식이 텍스트/JSON으로 고정됨 |
| 외부 제어용 RPC | 다른 프로세스나 서비스가 Pi를 원격 제어할 때 | RPC 서버 시작 후 클라이언트에서 JSON-RPC 호출 | 문서의 rpc.md 참고 |
| 임베디드 앱 개발용 TypeScript SDK | 자사 앱 안에 에이전트 루프를 내장하고 싶을 때 | import { createPi } from '@pi-agent/sdk' | npm 패키지로 제공, sdk.md 참고 |
각 모드는 확장·스킬·프롬프트 템플릿·테마를 공통으로 쓰니까, 모드만 바꿔도 기존 커스터마이징이 그대로 적용돼요.
실무에서 바로 써먹는 커스터마이징 포인트 5가지
Pi는 확장성에 초점을 맞춘 최소형 에이전트 툴킷이에요. 기본 기능만 제공하고, 필요에 따라 Extensions, Skills, Prompt Templates, Themes, Packages 다섯 가지 축을 자유롭게 붙일 수 있습니다. 현재 GitHub에서 11.2만 개의 스타(⭐111,771)를 받아 개발자 커뮤니티에서 활발히 사용되고 있죠. TypeScript 기반이며 MIT 라이선스로 자유롭게 수정·배포할 수 있습니다. 처음 만들어진 시점은 1년 2개월 전(2025년 8월)이고, 마지막 업데이트는 이번 달(2026년 10월)이라 최신 상태를 유지하고 있어요.
실무 시나리오와 맞춤 포인트 매핑
| 시나리오 | 맞춤 포인트 |
|---|---|
| 코드 리뷰 자동화 | Extensions + Skills |
| 레거시 마이그레이션 규칙 주입 | Prompt Templates + Packages |
| 팀 공유 스타일 가이드 | Themes + Packages |
예를 들어 코드 리뷰 자동화를 원한다면, extensions 폴더에 리뷰 자동화 모듈을 추가하고, skills에 리뷰 요약 스킬을 정의하면 됩니다. 레거시 마이그레이션 규칙은 프롬프트 템플릿에 규칙을 미리 넣고, 해당 템플릿을 하나의 패키지로 배포하면 팀 전체에서 재사용할 수 있어요. 스타일 가이드는 테마를 커스터마이징해 색상·아이콘·출력 형식을統一하고, 이를 패키지 형태로 npm에 퍼블리시하면 손쉽게 공유됩니다.
Extension 설치
1️⃣
pi update로 최신 Pi를 확보합니다. 2️⃣ 프로젝트 루트에extensions폴더를 만들고, 원하는 JavaScript/TypeScript 파일을 넣습니다. 3️⃣pi명령을 실행해 새 확장이 로드되는지 확인합니다.
pi update주의할 점과 다음 단계
자동 이슈·PR 종료 정책 숙지하기
Pi 저장소는 새 기여자의 이슈와 PR을 기본적으로 자동 종료합니다. 유지보수 팀이 매일 검토해 필요하면 다시 열지만, 처음 올린 글이나 요청이 바로 닫혀도 놀라지 마세요. 자세한 기준은 CONTRIBUTING.md에 정리돼 있습니다.
MIT 라이선스와 상업적 이용
라이선스는 MIT라 상업·비상업 구분 없이 자유롭게 쓰고 수정·배포할 수 있습니다. 단, 원저작자 표기와 라이선스 사본 포함 의무만 지키면 됩니다. 사내 도구나 고객 납품 제품에 녹여내도 법적 걸림돌은 없습니다.
Nix 안정 버전 고정·업그레이드 요령
Nixpkgs stable 채널은 최신 릴리스를 가리키며, 프로필 방식으로 설치·갱신합니다. 한 번 고정한 버전을 계속 쓰려면 특정 릴리스 태그를 명시하세요.
nix profile add github:earendil-works/pi/stable
nix profile upgrade pi # 안정 채널 따라 최신으로 갱신
# 버전 고정 예시
nix profile add github:earendil-works/pi/v0.12.3실전 통합 사례 — OpenClaw 참고하기
공식 README가 실전 예로 든 OpenClaw(github.com/OpenClaw/OpenClaw)는 Pi를 핵심 런타임으로 감싸 독자적인 에이전트 워크플로우를 구축한 프로젝트입니다. 확장 포인트(Extensions·Skills·Prompt Templates·Themes)를 패키지로 묶어 npm·git으로 배포하는 전형적인 패턴을 보여줍니다.
심화 학습 경로 — 공식 문서로 넘어가기
지금까지 설치·실행 모드·커스터마이징 5가지를 훑었습니다. 다음 단계는 pi.dev/docs 최신 버전 문서에서 아래 주제를 순서대로 파보는 것입니다.
- Extensions 작성 가이드 — 도구·후킹·상태 관리 API
- Skills 설계 패턴 — 단일 책임 원칙으로 잘게 쪼개기
- Prompt Templates & Themes — 프롬프트·UI 일관성 유지
- Pi Packages 배포 — npm/git 버전 관리·의존성 고정
- RPC / TypeScript SDK — 외부 앱에서 Pi 제어·임베드
- CLI 고급 플래그 — print·JSON·비대화형 자동화 스크립트