Pi 코딩 에이전트란? 설치부터 확장 기능·로컬 LLM 연동까지 총정리
Pi는 단순한 터미널 챗봇이 아니라, 개발자가 원하는 방식으로 직접 개조하고 확장할 수 있도록 설계된 터미널 기반 AI 코딩 하네스입니다. 이 글에서는 Pi의 핵심 철학, 설치 방법, 주요 기능, SDK·RPC 연동, 로컬 모델 활용법, 보안 주의사항까지 블로그용으로 깊이 있게 정리합니다.
- Pi는 확장 가능한 터미널 AI 코딩 하네스로, 사용자의 워크플로에 맞춰 바꾸는 것을 목표로 합니다.
- Interactive, Print/JSON, RPC, SDK 등 여러 실행 모드를 제공해 단독 사용과 임베딩을 모두 지원합니다.
- Extensions, Skills, Prompt Templates, Themes, Packages를 통해 기능을 조립하듯 확장할 수 있습니다.
- Ollama, vLLM, LM Studio 같은 로컬 모델 서버도
models.json을 통해 붙일 수 있습니다. - 다만 확장성과 패키지는 강력한 만큼 보안 검토가 필수입니다.
1. Pi란 무엇인가?
Pi는 공식적으로 “minimal terminal coding harness”를 표방합니다. 여기서 핵심은 “AI가 코딩을 도와주는 프로그램”이라는 결과보다, 개발자가 자신의 작업 방식에 맞게 AI 코딩 환경 자체를 조정할 수 있는 기반이라는 점입니다.
일반적인 AI 코딩 도구는 미리 정해진 기능 세트를 제공하는 경우가 많습니다. 반면 Pi는 코어를 가볍게 유지하고, 필요한 기능을 Extensions, Skills, Prompt Templates, Themes, Pi Packages로 확장하는 철학을 갖고 있습니다.
Pi는 “내 개발 흐름에 맞춰 직접 바꾸는 터미널형 AI 코딩 에이전트 프레임워크”에 가깝습니다.
2. Pi가 주목받는 이유
Pi의 가장 큰 차별점은 “기능을 많이 넣은 완성형 제품”보다 “유연하게 바꿀 수 있는 에이전트 기반 구조”를 우선한다는 점입니다. 공식 소개에서도 “Change the harness, not your workflow”라는 표현으로 이 방향성을 강조합니다.
3. Pi 설치 방법
공식 사이트는 쉘 스크립트 설치와 npm 계열 설치 방식을 함께 안내합니다. 가장 단순한 방식은 다음과 같습니다.
curl -fsSL https://pi.dev/install.sh | shNode.js 기반 패키지 매니저를 선호한다면 다음 방식도 가능합니다.
npm install -g @earendil-works/pi-coding-agent
pnpm add -g @earendil-works/pi-coding-agent
bun add -g @earendil-works/pi-coding-agent설치 후에는 인증을 설정하고, 터미널에서 Pi 세션을 시작해 바로 사용할 수 있습니다. 공식 문서는 구독 기반 인증과 API 키 방식 모두를 설명합니다.
4. Pi의 4가지 실행 모드
Pi는 대화형 터미널 도구에 머물지 않고, 자동화나 제품 통합을 고려한 여러 실행 모드를 제공합니다.
| 모드 | 설명 | 활용 예시 |
|---|---|---|
| Interactive | 터미널 TUI에서 직접 대화하며 사용하는 기본 모드 | 코드 수정, 프로젝트 분석, 명령 실행 |
| Print / JSON | pi -p 또는 JSON 이벤트 스트림 출력 |
쉘 스크립트, 배치 자동화, 파이프라인 연동 |
| RPC | stdin/stdout 기반 JSON 프로토콜로 에이전트 제어 | 비 Node 앱, IDE, 커스텀 UI와 연동 |
| SDK | Node.js 애플리케이션에 Pi 기능을 직접 임베딩 | 웹앱, 데스크톱 앱, 자동화 시스템 구축 |
예를 들어 단발성 요약 작업은 다음처럼 실행할 수 있습니다.
pi -p "Summarize this codebase"
cat README.md | pi -p "Summarize this text"
프로세스 연동이 필요한 경우에는 --mode rpc,
구조화된 이벤트 출력이 필요하면 --mode json을 사용할 수 있습니다.
5. 지원 Provider와 모델 선택 방식
Pi는 공식 문서에서 구독 기반 인증과 API 키 기반 인증을 모두 설명합니다. 구독 로그인 방식으로는 ChatGPT Plus/Pro(Codex), Claude Pro/Max, GitHub Copilot 등을 언급하고, API 키 방식은 OpenAI, Anthropic, Google, Mistral, Groq, Cerebras, OpenRouter 등 다양한 공급자를 지원합니다.
사용 중에는 /model 명령이나 단축키를 통해 모델을 전환할 수 있으며,
프로젝트 성격에 따라 빠른 모델과 추론형 모델을 바꿔 쓰는 운영이 가능합니다.
단순 코드 검색과 포맷 수정은 가벼운 모델로, 아키텍처 분석이나 복잡한 리팩터링은 고성능 모델로 나누면 비용과 속도를 함께 관리하기 좋습니다.
6. Ollama·vLLM·LM Studio 같은 로컬 LLM 연동
Pi가 특히 흥미로운 이유는 로컬 모델 서버와의 연결을 공식적으로 고려한다는 점입니다.
문서에 따르면 ~/.pi/agent/models.json을 사용해 Ollama, vLLM, LM Studio,
프록시 서버를 커스텀 Provider처럼 등록할 수 있습니다.
{
"providers": {
"ollama": {
"baseUrl": "http://localhost:11434/v1",
"api": "openai-completions",
"apiKey": "ollama",
"models": [
{ "id": "llama3.1:8b" },
{ "id": "qwen2.5-coder:7b" }
]
}
}
}
vLLM이나 일부 OpenAI 호환 서버에서는 developer role이나
reasoning_effort 지원 차이 때문에 추가 호환성 옵션이 필요할 수 있습니다.
공식 문서는 이를 위해 compat.supportsDeveloperRole,
compat.supportsReasoningEffort 설정 예시도 제공합니다.
- 자체 GPU 서버와 Pi를 연결해 사내 코딩 에이전트처럼 운용 가능
- Ollama나 vLLM 기반 모델 실험에 적합
- 코딩 하네스는 Pi, 추론 엔진은 자체 모델로 분리하는 구조를 만들기 쉬움
7. Pi의 컨텍스트 엔지니어링 기능
Pi는 코딩 에이전트의 품질을 좌우하는 핵심 요소로 컨텍스트 관리를 중요하게 다룹니다. 공식 소개와 문서는 다음 기능을 중심으로 이를 설명합니다.
| 기능 | 역할 |
|---|---|
AGENTS.md |
프로젝트 규칙, 명령어, 금지사항, 개발 관례를 로딩 |
SYSTEM.md |
기본 시스템 프롬프트를 프로젝트 단위로 교체 또는 보강 |
| Compaction | 대화가 길어질 때 오래된 문맥을 요약해 컨텍스트를 확보 |
| Skills | 필요할 때만 상세 지침을 불러오는 온디맨드 능력 패키지 |
| Prompt Templates | 자주 쓰는 요청 패턴을 재사용 가능한 템플릿으로 관리 |
| Dynamic Context | Extensions가 매 턴 전 메시지 삽입, 필터링, RAG, 메모리 구현 가능 |
특히 Compaction은 대화가 컨텍스트 한계에 가까워질 때 오래된 내용을 요약해
최근 작업을 유지하는 방식입니다. 공식 문서는 자동 압축뿐 아니라,
/compact 명령으로 수동 요약도 가능하다고 설명합니다.
8. Skills·Extensions·Packages의 차이
Pi를 제대로 이해하려면 확장 구조를 구분해서 보는 것이 중요합니다.
| 구성 요소 | 무엇을 확장하나? | 예시 |
|---|---|---|
| Skills | 특정 작업을 위한 지침·스크립트·참고 문서 | 배포 점검, PDF 처리, 코드 리뷰 워크플로 |
| Extensions | 명령어, 툴, 이벤트, TUI UI, 시스템 프롬프트 개입 | 커스텀 명령, RAG 주입, 상태바, MCP 구현 |
| Packages | Skills·Extensions·Themes·Templates를 묶어 배포 | npm 또는 git 기반 공유 패키지 |
공식 문서는 Skills를 “필요할 때만 전체 지침을 불러오는 점진적 공개 구조”로 설명합니다. Extensions는 TypeScript 모듈 형태로 더 깊은 수준의 기능 개입을 가능하게 하고, Packages는 이러한 구성 요소들을 묶어 팀이나 커뮤니티에 배포하는 방식입니다.
9. 세션 트리와 작업 흐름 관리
Pi는 세션을 단순한 선형 대화로 보지 않고, 트리 구조의 작업 기록으로 저장합니다. 이를 통해 이전 지점으로 돌아가 다른 방향으로 작업을 이어가거나, 분기된 흐름을 탐색할 수 있습니다.
/tree: 세션 내 특정 지점으로 이동/fork: 과거 메시지에서 새 흐름 생성/clone: 현재 활성 브랜치를 복제/resume: 이전 세션 재개
이 구조는 대규모 리팩터링, 실험성 높은 구현, 여러 접근법을 비교하는 코딩 작업에서 특히 유용합니다.
10. Pi가 일부 기능을 기본 내장하지 않는 이유
공식 사이트는 “What we didn’t build”라는 섹션에서 Pi가 일부 기능을 기본 내장하지 않는 이유를 설명합니다. Pi의 철학은 모든 기능을 코어에 넣는 것이 아니라, 필요한 사용자가 직접 조립하거나 설치하는 방향입니다.
| 기본 내장하지 않는 기능 | Pi가 제안하는 방향 |
|---|---|
| MCP | CLI 도구와 README 기반 Skills 활용 또는 Extension으로 직접 추가 |
| Sub-agents | tmux에서 Pi 인스턴스를 분리하거나 Extension으로 구현 |
| Permission popups | 컨테이너 실행 또는 자체 승인 흐름 구현 |
| Plan mode | 파일 기반 계획 또는 Extension/Package로 구현 |
| Built-in TODO | TODO.md 활용 또는 사용자 정의 기능 추가 |
| Background bash | tmux 사용 권장 |
즉 Pi는 “기능이 부족한 도구”라기보다, 기능의 기본값을 최소화하고 확장 가능성을 최우선에 둔 도구에 가깝습니다.
11. 설치 전 꼭 알아야 할 보안 주의사항
공식 문서는 Extensions가 전체 시스템 권한으로 임의 코드를 실행할 수 있다고 경고합니다. Packages 역시 Extensions와 Skills를 포함할 수 있으므로, 신뢰할 수 있는 출처인지 반드시 확인해야 합니다.
- 출처가 불명확한 Extension이나 Package는 설치하지 않기
- npm·git 패키지는 README와 소스코드 검토 후 사용하기
- 사내 코드베이스에서 쓸 경우 격리 환경이나 컨테이너 전략 검토하기
- 로컬 모델 서버와 붙일 때도 네트워크·권한 범위를 점검하기
12. 어떤 사용자에게 Pi가 잘 맞을까?
| 추천 대상 | 이유 |
|---|---|
| 터미널 중심 개발자 | 기존 CLI 작업 흐름을 바꾸지 않고 AI 기능을 덧붙이기 쉬움 |
| 로컬 LLM 실험자 | Ollama·vLLM·LM Studio와 연결해 모델별 코딩 성능을 비교하기 좋음 |
| 자체 에이전트 제품을 만드는 개발자 | RPC·SDK로 별도 UI나 서비스에 임베딩 가능 |
| 컨텍스트 엔지니어링에 관심 있는 팀 | AGENTS.md, SYSTEM.md, Compaction, Skills 조합을 실험하기 좋음 |
13. 실제 활용 시나리오
시나리오 1: 프로젝트별 코딩 규칙을 자동 반영
저장소 루트에 AGENTS.md를 두고 테스트 명령어, 금지 규칙, 코드 스타일을 적어두면
Pi가 세션 시작 시 해당 지침을 읽고 작업할 수 있습니다.
시나리오 2: vLLM 서버를 붙인 사내 코딩 에이전트
사내 GPU 서버에서 vLLM을 띄우고 Pi의 models.json으로 연결하면,
외부 API 의존도를 줄인 코딩 지원 환경을 구성할 수 있습니다.
시나리오 3: SDK로 자체 개발 도구에 에이전트 기능 내장
Node.js 앱 안에 Pi Agent 기능을 넣어 코드 분석, 이슈 요약, 자동 문서 생성처럼 반복되는 개발 업무를 제품 기능으로 만들 수 있습니다.
14. 자주 묻는 질문
성격이 조금 다릅니다. Pi는 특정 UI 경험을 강하게 밀어붙이는 제품이라기보다, 개발자가 자신의 워크플로에 맞게 확장하는 터미널형 코딩 하네스에 더 가깝습니다.
공식 문서에 models.json 예시가 제공되어 있어 구조 자체는 명확합니다.
다만 서버별로 호환성 옵션을 조정해야 할 수 있습니다.
확장성과 로컬 모델 연동, SDK/RPC 제공 측면에서는 충분히 검토할 만합니다. 다만 Extension·Package의 권한이 강하므로, 보안 정책과 소스 검토 체계가 함께 필요합니다.
MCP가 꼭 필요한 워크플로라면 아쉬울 수 있습니다. 반대로 Pi는 CLI 도구와 Skills, 그리고 Extensions를 통해 필요한 흐름을 직접 조립하는 방향을 택합니다.
15. 결론: Pi는 ‘확장 가능한 코딩 에이전트 기반’이다
Pi는 기능을 잔뜩 내장한 폐쇄형 도구라기보다, 개발자가 자신의 개발 환경과 AI 워크플로를 직접 설계할 수 있는 터미널 기반 코딩 하네스입니다.
특히 로컬 LLM 연동, SDK/RPC 기반 임베딩, Skills와 Extensions를 통한 세밀한 확장, 컨텍스트 관리 기능은 단순한 “AI 코드 보조 도구” 이상을 원하는 개발자에게 매력적인 선택지가 될 수 있습니다.
다만 Pi의 강점인 확장성은 동시에 보안 검토의 필요성을 뜻합니다. 따라서 실제 도입 시에는 패키지 출처, 권한 범위, 실행 환경 격리를 함께 고려하는 것이 좋습니다.
참고 자료
'AI' 카테고리의 다른 글
| Pi 패키지 총정리: 인기 확장 50개와 최신 패키지 8개 기능·설치 명령어 한눈에 (0) | 2026.05.17 |
|---|---|
| Qwen WebWorld-32B란? 웹 에이전트 학습용 월드 모델 특징과 사용법 총정리 (0) | 2026.05.16 |
| Sulphur-2-base란? LTX 2.3 기반 오픈 영상 생성 AI 모델 특징과 사용법 총정리 (1) | 2026.05.16 |
| Local Deep Research 사용법 완벽 가이드: 로컬 AI 딥리서치 설치부터 Ollama·SearXNG·Docker 실행까지 (0) | 2026.05.11 |
| Claude Code Haha 사용법 총정리: 설치부터 API 설정, Windows 실행, 데스크톱 UI까지 (0) | 2026.05.06 |