pi 에이전트 툴킷: 패키지 다섯 개, SDK 레시피, 판정표, 월요일 체크리스트

TL;DR

• pi는 MIT 라이선스 모노레포로, 코딩 에이전트 하네스를 다섯 개의 독립 패키지로 제공합니다. 모델 API 계층, 에이전트 루프, 터미널 UI 라이브러리, 코딩 에이전트 본체, 텔레메트리 패키지입니다. 하나만 가져다 써도 되고 다섯 개를 모두 써도 됩니다.
• CLI는 첫날부터 완결된 코딩 에이전트입니다. 기본 도구 네 개, 포크와 재개가 되는 트리 구조의 세션 기록, 실시간 비용 카운터가 있고, 저장소에 이미 있는 AGENTS.md나 CLAUDE.md도 읽습니다.
• 진짜 가치는 SDK 쪽에 있습니다. createAgentSession에 모델 런타임과 세션 매니저를 넘기면 약 열 줄의 TypeScript로 동작하는 에이전트가 생기고, defineTool로 별도 프로세스나 프로토콜 없이 타입이 지정된 커스텀 도구를 추가할 수 있습니다.
• 이런 투명성의 대가는 직접 해야 할 일입니다. 내장 권한 확인 프롬프트가 없고, 격리는 사용자 몫이며, 버전은 1.0 이전(v0.84)이고, 열린 이슈가 약 백 개입니다.
• 평소 쓰는 하네스는 그대로 두고, 그 하네스가 숨기는 것을 보여 주는 테스트 벤치로 pi를 쓰세요. 가드레일을 직접 책임질 각오가 있을 때만 그 위에 제품을 만드세요.

출처가 말하는 것

pi는 모노레포입니다. 하나의 저장소에서 다섯 개의 패키지를 따로 배포하며, 각 패키지가 하네스의 한 계층을 맡습니다 s2. pi-ai는 모델 제공자(OpenAI, Anthropic, Google 등)를 하나의 인터페이스로 묶는 통합 API이고, 응답 스트리밍, 사고 수준(thinking level)이 있는 추론 블록, 각 제공자가 내놓는 모델의 동적 탐색을 처리합니다 s2. pi-agent-core는 에이전트 루프 자체입니다. 대화 상태와, 메시지를 보내고 도구 호출을 읽고 실행하고 결과를 되돌려 주는 사이클을 담당합니다 s2. pi-tui는 차분 렌더링(differential rendering)을 쓰는 터미널 렌더링 라이브러리로, 화면에서 바뀐 부분만 다시 그립니다 s2. pi-coding-agent는 이 구성 요소를 조립해 설치하는 CLI로 만들고, pi-telemetry는 특정 벤더에 의존하지 않고 자체 사용량 지표를 연결하게 해 줍니다 s3.

도입 수치도 이 설계를 뒷받침합니다. 별 92 123개, 포크 11 400개, 커밋 5 700개 이상이며 전부 MIT 라이선스라서 상용 제품 안에서도 사용, 수정, 재배포가 가능합니다 s1. 릴리스 주기는 여름 내내 유지되었습니다. 8월 첫 2주 동안 세 번 릴리스되었고 v0.84.2는 14일에 나왔습니다 s4.

설치는 명령 한 줄, npm install -g --ignore-scripts @earendil-works/pi-coding-agent입니다. ignore-scripts 플래그는 중요합니다. 의존성이 설치 스크립트를 실행하지 못하게 막는데, 설치 스크립트는 npm에서 가장 많이 쓰이는 공격 경로 중 하나입니다 s3. login 명령으로 제공자에 연결하면 하단 바에 현재 폴더, 세션, 소비한 토큰, 실시간 비용이 표시되므로, 요청마다 월말이 아니라 나가는 순간에 가격을 알 수 있습니다 s3.

세션이 pi의 특징입니다. 모든 대화는 홈 폴더에 프로젝트별로 JSONL로 저장되고, 기록은 직선이 아니라 트리입니다. fork는 아무 지점으로 돌아가 가지를 치고, tree는 가지 사이를 오가며, resume은 모든 것이 로컬에 저장되어 있으므로 몇 주 뒤의 과거 세션도 다시 엽니다 s3. 모델이 기본으로 받는 도구는 read, write, edit, bash 네 개뿐입니다. 시중의 에이전트에 비하면 매우 적은데, 의도된 것입니다 s3. 설정도 같은 논리를 따릅니다. 홈의 전역 settings.json, 이를 덮어쓰는 프로젝트별 settings.json, 그리고 처음 여는 폴더의 로컬 설정을 적용하기 전에 확인을 묻는 신뢰 시스템입니다. CLI는 프로젝트의 AGENTS.md나 CLAUDE.md도 컨텍스트로 읽으므로 기존 지침을 다시 쓰지 않고 그대로 쓸 수 있습니다 s3.

SDK 쪽에서는 createAgentSession이 ModelRuntime과 SessionManager를 받아 동작하는 에이전트를 돌려줍니다. SessionManager는 영속성을 고르는 부분입니다. 한 번 쓰고 버릴 스크립트에는 메모리, 실행 사이에 대화를 다시 찾으려면 디스크를 쓰며, SDK가 만든 세션은 CLI 자체 세션과 같은 구조를 공유합니다 s8. createAgentSession의 옵션으로 노출할 도구 집합을 정확히 고를 수 있고, 백지에서 시작하고 싶다면 ResourceLoader를 통해 시스템 프롬프트 전체까지 바꿀 수 있습니다 s8. 커스텀 도구는 defineTool을 거칩니다. 이름, 설명, 타입이 지정된 파라미터 스키마, execute 함수를 만들어 createAgentSession의 customTools에 넘깁니다. 모델에게는 read나 bash와 똑같은 도구로 보이고, 타입 스키마 덕분에 에디터 자동완성이 되며, 에이전트는 이미 검증된 입력을 받습니다. MCP 서버와 같은 메커니즘이지만, 별도 프로세스도 중간 프로토콜도 없이 전부 사용자의 파일 안에 있습니다 s8.

CLI 자체는 네 가지 방식으로 커스터마이즈하며, 모두 프로젝트나 홈 폴더 안에 둡니다. 확장(extensions: 도구, 슬래시 명령, 단축키, UI 요소를 등록하고 extensions 폴더에서 시작 시 로드되는 TypeScript 모듈), 스킬(Agent Skills 표준을 따르는 기능 패키지로, 모델이 호출하거나 직접 부르므로 기존 스킬을 그대로 재사용), 프롬프트 템플릿, 그리고 CLI가 실행되는 동안 다시 로드되는 테마입니다 s3. README는 철학을 한 줄로 밝힙니다. 포크하거나 내부를 건드리지 말고, pi를 워크플로에 맞추라는 것입니다 s3. 대형 하네스가 서브 에이전트, 플랜 모드, 권한을 제품에 묶어 두는 것과 달리 pi는 의도적으로 이를 빼 두었고, 확장으로 직접 작성하거나 커뮤니티에서 설치하게 합니다 s3.

한계는 프로젝트가 직접 문서화해 두었습니다. 내장 권한 프롬프트가 없어서 기본적으로 에이전트는 묻지 않고 bash 명령을 실행할 수 있습니다. 공식 컨테이너화 가이드도 이를 인정하고 Docker를 포함한 세 가지 격리 패턴을 제안하지만, 중요한 머신에서 에이전트를 풀어 놓기 전에 격리를 구성하는 일은 사용자의 몫입니다 s5. 성숙도가 또 다른 비용입니다. 1.0이 아닌 v0.84, 열린 이슈 약 백 개, 그리고 최근 몇 주 사이에 추가된 원격 세션 클라이언트처럼 아직 실험적으로 표시된 API가 있습니다 s7. 같은 구성 요소가 이미 다른 제품에도 쓰이고 있습니다. pi-chat은 이를 대화 자동화에 적용합니다 s6.

판정: 유지, 시도, 보류

월요일에 할 일

• npm install -g --ignore-scripts @earendil-works/pi-coding-agent로 CLI를 설치하고 pi를 실행해 login 명령으로 제공자를 연결한 뒤, 실제 작업 하나를 하는 동안 비용 바를 지켜보세요.
• 이미 AGENTS.md나 CLAUDE.md가 있는 저장소를 열어 pi가 이를 읽는지 확인하고, 같은 프롬프트로 평소 쓰는 하네스와 에이전트의 첫 답변을 비교하세요.
• 대화를 하나 진행한 뒤 이전 노드에서 fork로 다른 방향을 잡아 보고, ~/.pi/agent/sessions/를 열어 JSONL 파일과 프로젝트 폴더를 확인하세요.
• 스무 줄짜리 our-agent.ts를 작성하세요. createAgentSession을 import하고 ModelRuntime과 메모리 SessionManager를 넘겨 현재 폴더에 무엇이 있는지 물은 뒤, npx tsx로 실행합니다.
• 자신의 시스템(내부 API, 데이터베이스 뷰, CSV)에서 무언가를 읽는 defineTool을 하나 추가해 customTools에 넘기고, 관련 질문에 에이전트가 시키지 않아도 그 도구를 호출하는지 확인하세요.
• 중요한 머신에서 bash가 활성화된 실행을 하기 전에, 컨테이너화 가이드의 세 가지 격리 패턴 중 하나를 골라 구성하세요.
• bash 호출을 가로채 파괴적인 명령에 확인을 묻는 첫 확장을 초안으로 작성하고, 프로젝트의 extensions 폴더에서 버전 관리하세요.
• 열린 이슈 목록을 한 번 훑어서, 그 위에 만들기 전에 어떤 부분이 바뀌는지 파악하세요.

더 읽을거리

• 도구 집합, ResourceLoader를 통한 시스템 프롬프트, 세션 매니저 등 createAgentSession 옵션 전체는 SDK 문서에서 읽으세요 s8.
• 사용자의 머신에서 bash를 실행하는 무언가를 내놓기 전에 컨테이너화 가이드의 세 가지 격리 패턴을 살펴보세요 s5.
• 같은 다섯 패키지가 코딩이 아닌 대화 자동화를 위해 어떻게 재배치되는지 pi-chat에서 확인하세요 s6.
• packages 폴더를 둘러보고 pi-agent-core를 따로 읽어 보세요. 모든 번들 하네스가 돌리는 루프를 가장 작게 읽을 수 있는 형태입니다 s2.
• 릴리스 페이지를 팔로우하세요. v0.84.0에서 v0.84.2까지 8월의 2주 안에 나왔으므로 확장에 영향을 주는 변경 노트가 나올 수 있습니다 s4.
• 열린 이슈를 아직 실험적인 부분의 지도로 쓰고, 원격 세션 클라이언트부터 보세요 s7.
• 다른 도구용으로 이미 작성한 스킬을 재사용하세요. pi의 스킬 폴더는 Agent Skills 표준을 따릅니다 s3.

출처

• pi: the agent toolkit (repository), Earendil Works. 읽어야 하는 이유: 패키지 목록, 별과 포크 수, MIT 라이선스가 있는 README입니다.
• pi monorepo packages, Earendil Works. 읽어야 하는 이유: 다섯 패키지를 나란히 보여 주어 각각 어느 계층을 맡는지 가장 빨리 알 수 있습니다.
• pi-coding-agent package README, Earendil Works. 읽어야 하는 이유: 설치 명령, 기본 도구, 세션, 네 가지 확장 메커니즘이 있습니다.
• pi releases, Earendil Works. 읽어야 하는 이유: v0.84 라인의 릴리스 주기와 변경 내역입니다.
• pi containerization guide (isolation patterns), Earendil Works. 읽어야 하는 이유: 중요한 곳에서 bash를 켜기 전에 적용할 세 가지 격리 패턴입니다.
• pi-chat: the same bricks applied to conversation automation, Earendil Works. 읽어야 하는 이유: 같은 패키지로 만든 두 번째 제품으로, 패키지의 재사용성을 가늠하는 데 유용합니다.
• pi open issues, Earendil Works. 읽어야 하는 이유: 현재 버전에서 불안정하거나 실험적인 부분의 실시간 목록입니다.
• pi-coding-agent SDK documentation (createAgentSession options), Earendil Works. 읽어야 하는 이유: createAgentSession, defineTool, 세션 매니저의 정확한 옵션 이름입니다.

FAQ

지금 pi가 매일 쓰는 코딩 에이전트를 대체할 수 있나요?

그대로 갈아끼우기는 어렵습니다. 권한 프롬프트가 없고, 격리는 사용자 몫이며, 버전은 1.0 이전에 열린 이슈가 약 백 개입니다. 업무에는 지금 쓰는 하네스를 유지하고 pi는 옆에서 돌려 보세요.

pi에 커스텀 도구를 주려면 MCP가 필요한가요?

아니요. defineTool은 이름, 설명, 타입이 지정된 파라미터 스키마, execute 함수를 받고, 그 도구를 createAgentSession의 customTools에 넘깁니다. 별도 프로세스나 프로토콜 없이 내장 도구처럼 동작합니다.

기존 AGENTS.md, CLAUDE.md, 스킬이 그대로 동작하나요?

네. CLI는 프로젝트의 AGENTS.md나 CLAUDE.md를 자동으로 로드하고, 스킬 폴더는 Agent Skills 표준을 따르므로 기존 스킬이 그대로 로드됩니다.

기본 도구가 왜 네 개뿐인가요?

read, write, edit, bash가 기본 세트의 전부이며 시중의 에이전트보다 훨씬 적습니다. 프로젝트는 이를 하나의 선택으로 설명합니다. 그 밖의 것은 customTools나 확장으로 의도적으로 추가합니다.