pi 속으로, 9.2만 스타 툴킷으로 나만의 에이전트 만들기

Claude Code, Codex, Gemini CLI는 다른 누군가가 설계한 에이전트 하니스다. 그리고 그중 하나 안에서 하루하루 일한다면, 당신은 그 설계 결정과 함께 사는 셈이다. 어떤 동작을 바꾸고 싶고, 툴을 추가하고 싶고, 권한 규칙을 조이고 싶은가? 벤더가 내킬 때 내놓기만 기다려야 한다. 시스템 프롬프트에 뭐가 있는지 모르고, 툴을 돌리는 루프도 보이지 않으며, 그중 무엇도 바꿀 수 없다. 그런데도 이 툴들은 이미 수천 개발자의 주 작업대가 되어 있다.

한 오픈소스 프로젝트는 정반대 길을 택했다. pi, 모델 커넥터부터 인터페이스까지 자신만의 에이전트를 조립할 부품을 제공하는 툴킷이다. 첫해에 GitHub 스타 9만 2000개를 얻었고, 거의 매주 릴리스를 낸다. 이 글에서는 pi가 실제로 상자 안에 뭘 담고 있는지, SDK로 자신만의 에이전트를 어떻게 만드는지, 그리고 완성형 하니스 대비 솔직한 평가를 다룬다.

하니스란 언어 모델을 작동하는 에이전트로 바꾸는, 그 주변의 모든 기계장치다. 모델 혼자서 할 수 있는 건 딱 하나뿐이다. 텍스트를 읽고 텍스트를 만드는 것. 파일을 읽지도, 명령을 실행하지도 않으며, 세션이 바뀌면 아무것도 기억하지 못한다. 나머지는 전부 하니스다. 모델을 규정하는 시스템 프롬프트, 모델에 제공되는 툴, 툴 호출을 실행하고 결과를 돌려주는 루프, 그리고 터미널의 인터페이스.

하니스는 매일의 차이를 만드는 세부까지 결정한다. 컨텍스트가 넘칠 때 기록을 어떻게 압축하는지, 툴 오류가 모델에게 어떻게 돌아가는지, 뭘 로그로 남기고 뭘 남기지 않는지. Claude Code도 하니스다. Codex도 마찬가지다. 어떤 에이전트에 감탄했다면, 그 공의 상당수는 모델이 아니라 이 기계장치의 몫이다. 같은 모델을 서로 다른 두 하니스에 꽂으면 전혀 다른 수준의 에이전트 둘이 나온다.

Earendil Works가 만든 pi는 그 기계장치를 재사용 가능한 블록으로 쪼갰다. 코딩 에이전트를 그대로 써도 되고, 블록을 하나씩 가져다 직접 조립해도 된다. 우리가 관심 있는 건 두 번째 쪽이다.

pi는 모노레포다. 하나의 저장소에 따로 배포되는 다섯 패키지가 담겨 있고, 각 패키지가 하니스의 한 층을 맡는다.

패키지	하는 일
pi-ai	OpenAI, Anthropic, Google 등으로 가는 통합 API. 응답 스트리밍, 사고 레벨이 있는 추론 블록, 각 공급자가 제공하는 모델의 동적 탐지까지 처리한다. 인자 하나만 바꿔 랩을 갈아탄다.
pi-agent-core	에이전트 루프 그 자체. 대화 상태, 그리고 메시지를 보내고, 툴 호출을 읽고, 실행해서 작업이 끝날 때까지 결과를 돌려주는 주기. 실패하는 툴, 중간에 끊기는 응답, 동시에 도착하는 호출 같은 까다로운 케이스는 이미 처리돼 있다.
pi-tui	차등 렌더링을 쓰는 터미널 렌더링 라이브러리. 화면에서 바뀐 부분만 다시 그린다.
pi-coding-agent	위 블록들로 조립된 완전한 코딩 에이전트. 이 툴킷만으로 완성품을 만들 수 있다는 증거다.
pi-telemetry	벤더에 의존하지 않고 자체 사용 지표를 붙일 수 있게 해준다.

에이전트 루프는 처음부터 만들면 엉망이 되기 쉬운 바로 그 부분이다. 제대로 짜는 데 몇 주가 걸리는데, 임포트 한 번으로 그걸 얻는다. 팀은 같은 레시피를 다른 곳에도 적용한다. 별도 저장소 pi-chat은 같은 블록을 대화 자동화에 재사용한다.

숫자가 이 공식이 통한다는 걸 보여준다.

지표	값
GitHub 스타	92,123
포크	11,400
커밋	5,700개 이상
라이선스	MIT
2026년 8월 첫 두 주의 릴리스	3회 (v0.84.2는 8월 14일 출시)

MIT 라이선스라는 것은 상용 제품에서도 포함해 제약 없이 쓰고, 고치고, 재배포할 수 있다는 뜻이다. pi는 그저 또 다른 프레임워크가 아니다. 부품으로 나온 완전한 하니스이며, 꾸준한 속도로 유지되고 있다.

pi의 CLI는 코드 한 줄 건드리기 전에 손에 들어오는, 이미 조립된 코딩 에이전트다. 여기서부터 시작하게 된다. 설치는 한 줄이고, --ignore-scripts 플래그는 사소하지 않다. 의존성이 자체 설치 스크립트를 실행하지 못하게 막는데, npm에서 가장 많이 악용되는 공격 표면 중 하나다. pi를 실행하고 login 명령으로 공급자를 연결하면, 터미널 안에 바로 코딩 에이전트가 생긴다. 상태 바에는 현재 폴더, 세션, 사용한 토큰, 그리고 실시간 비용이 표시된다. 월말에 청구서를 발견하는 대신, 요청이 나가는 순간 가격이 매겨지는 걸 보게 된다.

슬래시 명령이 일상을 다룬다. model로 도중에 모델을 바꾸고, compact로 컨텍스트가 부풀 때 기록을 요약하고, export로 대화를 꺼내고, 나머지는 settings. prompts 폴더의 마크다운 파일 하나가, 이름만 쳐서 실행하는 명령이 된다.

pi의 진짜 정체성은 세션 처리에 있다. 모든 대화는 프로젝트별로 홈 폴더에 JSONL로 저장된다. 그리고 기록은 사실 선이 아니라 트리 구조다. 대화의 어느 지점으로든 돌아갈 수 있고 fork 명령으로 다른 길을 갈 수 있으며, tree로 브랜치 사이를 이동한다. 실패한 프롬프트는 이제 아무것도 잃지 않는다. 이전 노드로 돌아가 다시 시도하면 되고, 다른 브랜치는 그대로 남는다. 모든 게 로컬에 저장되니, resume은 몇 주가 지나도 어떤 과거 세션으로든 돌려준다. Claude Code도 Codex도 이런 형태의 기록 탐색은 제공하지 않는다.

기본값으로 모델은 딱 네 개의 툴만 받는다. read, write, edit, bash. 시장의 에이전트들에 비하면 아주 적은데, 의도적인 선택이다(아래에서 다시 다룬다). 설정도 같은 논리를 따른다. 홈 폴더의 전역 설정 파일 하나, 그걸 덮어쓰는 프로젝트별 파일 하나, 그리고 처음 여는 폴더의 로컬 설정을 적용하기 전에 물어보는 신뢰 시스템. 마이그레이션할 때는, pi가 기존 AGENTS.md나 CLAUDE.md를 자동으로 컨텍스트로 불러오므로 기존 지침이 다시 쓰지 않고도 작동한다.

pi의 SDK로 에이전트를 만드는 건 임포트 하나에서 시작한다. createAgentSession에 모델 런타임과 세션 매니저를 넘기면 작동하는 에이전트가 돌아온다. 세션 매니저는 영속성 선택지다. 일회성 스크립트라면 메모리에, 실행마다 대화를 다시 찾고 싶다면 디스크에 저장한다.

로컬 프로젝트에 시험해 봤다. 우리 스크립트가 현재 폴더에 뭐가 있는지 물으면, 에이전트가 read 툴을 불러 폴더를 읽고 답한다. 그게 전체 루프이고, 우리가 짰으며, TypeScript 약 10줄이면 충분했다. SDK가 만드는 세션도 CLI와 같은 트리 구조를 가진다. 각 메시지가 부모에 연결되어, 기록 분기가 당신 코드 안에서도 작동한다.

흥미로워지는 건 커스텀 툴부터다. defineTool은 이름, 설명, 타입이 있는 파라미터 스키마, execute 함수를 받고, 그러면 그 툴은 read나 bash와 똑같이 모델에 나타난다. 채널의 영상 목록을 조회하는 툴을 만들어 customTools에 넣었더니, 첫 관련 질문이 나오자마자 에이전트가 스스로 불렀다. 이건 기본적으로 MCP 서버와 같은 메커니즘인데, 다른 점은 모든 게 당신 파일 안에 있고 별도 프로세스도 그 사이의 프로토콜도 없다는 것이다. 파라미터 스키마에 타입이 있으니, 에디터가 인자를 자동 완성해 주고 에이전트는 이미 검증된 입력을 받는다.

모델도 제어할 수 있다. 완전 꺼짐부터 최대까지의 사고 레벨, 모델이 보는 정확한 툴 목록, 그리고 백지에서 시작하고 싶다면 리소스 로더로 시스템 프롬프트 전체까지도. 표시를 위해서는 session.subscribe가 모든 이벤트, 스트리밍 텍스트, 툴 호출, 오류를 준다. 원하는 어디로든 보낼 수 있다. 터미널, 메시징 봇, 또는 풀 리퀘스트에 댓글을 다는 CI 파이프라인으로도. 한나절 만에 에이전트를 쓰던 사람에서 만든 사람이 되고, 루프의 매 턴마다 무슨 일이 일어나는지 알게 된다.

pi의 CLI는 네 가지 방식으로 커스터마이즈할 수 있다. 모두 프로젝트나 홈의 평범한 폴더에 있다.

• Extensions — 툴, 슬래시 명령, 키보드 단축키, UI 요소를 등록하는 TypeScript 모듈. extensions 폴더에 파일을 두면 실행 시 로드된다. 예를 들어 권한 가드를 쓰기 딱 좋은 자리다. bash 명령을 가로채서 위험한 것 앞에서 확인을 요구하는 확장 같은 것.
• Skills — Agent Skills 표준을 따르는 능력 패키지. Anthropic이 대중화한 것과 같은 표준이라, 기존 skills를 그대로 재사용할 수 있다.
• Prompts — 재사용 가능한 프롬프트를 마크다운 파일로.
• Themes — CLI 실행 중 핫 리로드된다.

이 모든 게 다른 패키지처럼 설치된다. pi install은 npm 패키지나 git 저장소를 받고, 명령 하나로 전부 업데이트한다. 문서는 그 철학을 한 문장으로 요약한다. 포크나 내부 패치 없이, pi를 당신의 워크플로에 맞추는 것이지 그 반대가 아니다.

이건 대형 하니스와 정반대다. Claude Code가 서브 에이전트, 플랜 모드, 권한을 제품 안에 담는 반면, pi는 의도적으로 그것들을 빼놓는다. 확장으로 만들거나 커뮤니티에서 설치하도록 말이다. 판돈은 명확하다. 거의 안 움직이는 최소한의 코어, 그리고 모든 커스터마이즈는 당신 쪽에 사는 것. 프로젝트와 함께 버전 관리하는 파일들 속에.

pi의 투명성은 작업량으로 치러진다. 그 대가는 세 부분으로 나뉜다.

먼저 가드레일. 기본값으로는 내장 권한 확인이 없어서, 에이전트는 아무것도 묻지 않고 bash 명령을 실행할 수 있다. 공식 문서도 이를 인정하고 Docker를 포함한 세 가지 격리 패턴을 제안하지만, 중요한 머신에 에이전트를 풀어놓기 전에 그걸 갖추는 건 당신의 몫이다.

다음은 성숙도. 이건 v0.84이지 1.0이 아니다. 약 100개의 열린 이슈와, 최근 몇 주 사이 추가된 원격 세션 클라이언트처럼 아직 실험적으로 표시된 API 몇 개가 있다. 오늘 작동하는 것이 다음 릴리스에서 깨질 수 있으며, 이만큼 빠르게 움직이는 프로젝트의 정상적인 대가다.

마지막으로 시간. Claude Code가 기본으로 주는 모든 편의, 즉 플랜 모드, 서브 에이전트, 세밀한 권한까지, 여기서는 직접 만들어야 할 프로젝트가 되거나 유지되길 바라며 쫓아다녀야 할 커뮤니티 패키지가 된다. 확장 생태계는 아직 1년밖에 안 됐다. 완성된 패키지보다 채워야 할 구멍을 더 많이 만날 것이다. 설치 과정 자체가 --ignore-scripts 플래그를 통해 필요한 경계 수준을 이미 알려줬고, 그 수준을 사슬 전체에서 유지해야 한다. 목표가 오늘 밤 코드를 출시하는 거라면, pi는 속도를 내주기 전에 먼저 늦출 것이다. 이 영상 하나만 보고 이번 주에 메인 하니스를 바꾸지는 말자.

pi는 하나가 아니라 여러 에이전트로 제품을 만드는 개발자를 위한 것이다. 그들에게는 지금으로서는 아마 최고의 학습 투자일 것이다. CLI를 설치하고, SDK로 20줄짜리 에이전트를 짜고, 자신만의 툴 하나를 줘 보자. 그렇게 하면 대부분의 사용자보다 Claude Code를 더 잘 이해하게 된다.

오늘 그저 생산적인 비서만 필요하다면, 통합 하니스를 계속 쓰다가 1.0이 가드레일을 갖추면 돌아오자. pi의 가치는 이해와 통제에 있지, 즉각적인 편안함에 있지 않다. 그리고 둘 사이에는 위험 없는 중간 지대가 있다. 업무는 Claude Code로 계속하고, pi는 메인 툴이 뭘 숨기고 있는지 알아보는 시험대로 쓰는 것.

가장 크게 배운 점은 하니스가 더는 블랙박스가 아니라는 것이다. 부품들이 테이블 위에 있고, 문서화돼 있고, MIT 라이선스다. 다음번에 어떤 에이전트가 당신을 감탄시키거나 짜증나게 할 때, 어느 부품을 봐야 할지 정확히 알게 될 것이다.