pi.dev 코딩 에이전트 - 토큰 소비량도 적고 최적화된 코딩 하네스(harness)

실험 결과부터 제시한다 — 클로드 코드 1만 토큰, pi는 200토큰이다

 

각설하고 결론부터 박는다. 클로드 코드(Claude Code) 시스템 프롬프트가 약 1만 토큰인데, pi 코딩 에이전트는 200토큰 미만으로 시작한다. 약 50배 차이다. 처음 접했을 때 적잖이 충격이었다. AI 코딩 에이전트가 점점 무거워지는 시대에 반대 방향으로 달리는 도구가 갑자기 GitHub 49.8k stars를 찍으면서 화제가 된 것이다.

 

비유하자면, 클로드 코드가 "모든 옵션이 다 달린 외제 SUV"라면 pi는 "엔진과 핸들만 있는 카트"다. 처음엔 "이게 전부인가?" 싶지만, 막상 타보면 "오히려 이쪽이 더 빠른 것 아닌가?" 하는 인상을 받게 된다. 이 글에서는 pi가 정확히 무엇이고, 왜 갑자기 유명해졌으며, 5분 안에 직접 설치해 돌리는 법까지 다룬다. 클로드 코드를 잘 쓰고 있는 사람이 갈아탈 만한지도 솔직하게 검증해봤다.

 

참고로 이 글은 2026년 5월 시점 기준이다. pi 버전 v0.74.0, GitHub 49.8k stars, 커뮤니티 패키지 2,143개 상태에서 직접 설치해 정리한 내용이다.

 

pi 한 줄 정의: "내가 안 쓰는 기능은 안 만드는 코딩 하네스"이다

 

pi 코딩 에이전트의 정체는 한 줄로 정리된다. "제작자 본인이 쓸 기능만 넣은 극단적 미니멀 코딩 하네스(harness)" 이다. 하네스라는 단어가 다소 생소할 수 있는데, AI 모델에 도구와 컨텍스트를 입혀 실제로 일하게 만드는 "마구(馬具)"와 같은 것이라고 보면 된다. 모델이 말이라면, 하네스는 말에 채우는 안장이다. 안장이 너무 무거우면 말이 달릴 수 없다. pi 철학은 "안장을 좀 가볍게 하자"이다.

 

만든 사람이 Mario Zechner — libGDX를 만든 개발자이다

 

pi 원작자는 Mario Zechner다. 자바 게임 개발자라면 무조건 한 번은 들어봤을 libGDX 프레임워크를 만든 사람이다. 게임 엔진을 만들던 개발자가 코딩 에이전트를 만든 것이니, "오버엔지니어링을 싫어한다"는 성향이 DNA에 박혀 있는 셈이다. 본인이 2025년 11월 30일 블로그 글에서 회고한 바로는, 클로드 코드를 쓰다가 "내가 필요 없는 기능이 너무 많다, 내가 다시 만든다면 어떻게 만들 것인가?"라는 질문에서 출발한 프로젝트라고 한다.

 

어디서 동작하는가 — 터미널 TUI와 Node.js

 

pi는 터미널 UI(TUI) 환경에서 동작한다. Node.js 기반이고, npm으로 설치하거나 curl 스크립트 한 줄로 설치할 수 있다. VS Code 같은 IDE 통합은 제공하지 않는다. 그냥 터미널에서 pi를 치고 대화창에 코딩을 시키는 방식이다. macOS, Linux, WSL에서 잘 돌아가며 Windows도 일단 지원된다.

 

라이선스와 비용 — MIT 코어, 무료이다

 

코어 코드는 MIT 라이선스라 자유롭게 가져다 쓸 수 있다(Earendil RFC 0015에서 확정됐다). 부가 기능이나 상용 레이어는 Fair Source로 갈 수 있다는 방침이지만, 개인이 자기 컴퓨터에서 쓰는 것은 100% 무료다. 모델 API 비용만 본인 부담이다. Anthropic Pro/Max 구독자라면 그 계정으로 OAuth 로그인이 가능하다(뒤에 설명한다).

 

pi가 갑자기 유명해진 진짜 이유 세 가지

 

pi는 사실 2025년 11월쯤 조용히 공개되었다. 그런데 2026년 봄에 갑자기 X(트위터)와 해커뉴스에서 폭발적인 반응을 얻었다. 이유는 정확히 세 가지다.

 

이유 1: Armin Ronacher가 회사를 차려 인수해버렸다

 

2026년 4월 8일에 큰 뉴스가 나왔다. Armin Ronacher가 공동창업한 Earendil Inc. 가 pi를 인수했다는 발표였다. Armin이 누군지 모르는 독자를 위해 설명하자면, Python의 Flask 프레임워크를 만든 사람이다. Sentry 초창기 기술 리더기도 했으며, 파이썬 생태계에서 거의 신적 존재로 통하는 개발자다.

 

Armin 본인 블로그 글에서 인수 배경을 직접 설명하고 있다. "Mario가 만든 pi 철학이 우리가 만들고 싶었던 것과 똑같아서, 함께 가기로 했다"는 식이다. Flask를 만든 사람이 미니멀 코딩 에이전트를 인수했다는 사실 자체가 메시지다. "프레임워크는 가벼워야 한다"는 그의 일관된 철학이 AI 시대로 이어진 것이다.

 

이유 2: "하네스 반란(harness rebellion)" 프레임이 통했다

 

해외에서는 implicator.ai의 "Pi is not a Claude Code rival, it is a harness rebellion" 같은 글이 바이럴을 탔다. "이것은 단순한 클로드 코드 대안이 아니라, 하네스 자체에 대한 반란이다"라는 프레임이다. 모델 성능 경쟁만 할 것이 아니라, 그 위에 올라가는 하네스를 어떻게 짤지를 진지하게 생각하자는 운동의 깃발이 된 것이다.

 

한국에서도 비슷한 흐름이다. 패스트캠퍼스에서 "전현준의 하네스 엔지니어링: Claude code · Codex 완벽 가이드" 같은 강의가 나왔고, 위키독스에 "박재홍의 실리콘밸리: 모델이 아니라 하네스가 승부를 가른다" 글도 올라와 있다. 키워드 자체가 급상승 중이다.

 

이유 3: Peter Steinberger가 OpenClaw를 pi 위에 만들었다

 

iOS 개발자 사이에서 유명한 Peter Steinberger(PSPDFKit 창업자)가 OpenClaw라는 프로젝트를 pi 위에 올려서 만들었다. 즉 pi가 "다른 사람들이 그 위에 자기 에이전트를 빌드할 수 있는 베이스" 역할을 한다는 증명이 된 것이다. 미니멀해야 그 위에 무엇이든 쌓을 수 있다. 1만 토큰짜리 시스템 프롬프트 위에는 무엇도 쌓기 어렵다.

 

클로드 코드와 pi의 차이는 무엇인가 — 비교표로 정리한다

 

말로 백번 설명하는 것보다 표 한 장이 낫다. 직접 비교해 정리했다.

 

항목	Claude Code	pi
시스템 프롬프트 토큰	약 10,000	200 미만
기본 도구 개수	풀세트(약 15개)	4개 (read, write, edit, bash)
MCP 지원	O	X (의도적으로 제외)
Sub-agents	O	X
Plan mode	O	X
권한 팝업	O	X
멀티 프로바이더	Anthropic 위주	Anthropic, OpenAI, Gemini, Groq 등 20+
라이선스	비공개(상용)	MIT (코어)
익스텐션	마켓플레이스	TypeScript로 직접 작성
가격	구독	무료 (모델 API 비용만)

 

시스템 프롬프트 토큰 수 — 진짜 50배 차이다

 

이것이 가장 충격적인 부분이다. pi는 시스템 프롬프트가 200토큰 미만으로 시작한다. 클로드 코드는 약 1만 토큰이다. 왜 이것이 중요한가? 시스템 프롬프트는 매 요청마다 함께 전송되어 컨텍스트 윈도우를 잡아먹는다. 200을 잡아먹는 것과 1만을 잡아먹는 것의 차이는 크다.

 

기본 도구 4개만 — read, write, edit, bash

 

pi의 기본 도구는 단 4개다. 파일 읽기, 쓰기, 편집, 셸 실행. 그것이 전부다. grep, glob, web search, todo 관리 같은 것은 모두 없다. "그러면 어떻게 일하는가?" 라고 묻는다면, bash로 다 한다. grep 명령어를 쓰면 되고, find를 쓰면 되며, curl을 쓰면 된다. AI에게 도구 100개를 가르치느니, 30년 묵은 UNIX 도구들을 활용하게 하자는 발상이다.

 

의도적으로 뺀 기능 5개 — MCP, sub-agents, plan mode, 권한 팝업, 빌트인 todo

 

pi 공식 문서에는 "안 만들 것 리스트"가 있다. MCP(Model Context Protocol)를 지원하지 않고, sub-agents를 만들지 않으며, plan mode를 넣지 않고, 권한 확인 팝업이 없으며, 빌트인 todo 트래커도 없다. 이를 들으면 "그러면 무엇이 남는가?" 싶겠지만, 뺐기 때문에 빠른 것이다. 클로드 코드를 쓰다 보면 "이 명령어를 실행해도 되는가?" 하는 팝업이 짜증날 때가 있는데, pi는 그런 것 없이 그냥 실행한다. 위험할 수도 있다. 다만 시니어 개발자에게는 그쪽이 더 편하다.

 

멀티 프로바이더 — 20개 이상 지원한다

 

pi는 한 모델에 묶이지 않는다. Anthropic Claude, OpenAI GPT-4o, Google Gemini, Groq, DeepSeek, Mistral, Azure 등 20+ 프로바이더를 모두 지원한다. /model 명령어로 즉시 갈아탈 수 있다. 클로드 코드는 기본적으로 Anthropic 중심이다. 모델을 비교하면서 쓰고 싶은 사람에게는 pi가 압승이다.

 

pi 설치하고 5분 안에 돌려본다

 

이제 실전이다. 진짜 5분 컷이 가능하다.

 

설치 방법 — 둘 중 하나 고르면 된다

 

curl로 설치하거나, npm으로 설치하거나 둘 중 하나다.

 

# 방법 1: curl 한 줄
curl -fsSL https://pi.dev/install.sh | sh

# 방법 2: npm
npm install -g @earendil-works/pi-coding-agent

 

curl 방식이 더 간단하고, npm은 Node.js 환경이 갖춰진 사람에게 편하다. macOS, Linux는 curl을 추천한다. Windows는 WSL을 통해 설치하거나, npm 방식을 추천한다.

 

인증 — API 키 또는 구독 로그인

 

두 가지 방법이 있다. Anthropic API 키를 발급받아 쓰거나, Claude Pro/Max 구독 계정으로 로그인하거나이다.

 

# 방법 1: API 키 환경변수
export ANTHROPIC_API_KEY=sk-ant-...

# 방법 2: 구독 계정 로그인 (Pro/Max 사용자)
pi
> /login

 

Claude Pro/Max 구독자도 /login으로 OAuth 인증이 가능하다. 다만 2026년 4월 이후 Anthropic이 서드파티 하네스에 대해 구독 사용량을 따로 분리해서 토큰당 청구하는 정책으로 바뀌었다. 즉 Pro/Max 한도를 그대로 끌어 쓰지는 못하고, 별도 사용량으로 빠지는 것이라 100% 공짜는 아니라는 점은 알아두는 것이 좋다. /login을 입력하면 브라우저로 OAuth 인증 페이지가 열리고, 거기서 승인하면 완료된다.

 

첫 대화 시작 — pi를 치면 끝이다

 

설치와 인증이 끝났으면 그냥 터미널에 pi를 치면 된다.

 

pi

 

대화창이 뜨고, 거기서 "이 폴더 코드 살펴보고 README 작성해줘" 같은 요청을 시키면 된다. AGENTS.md 파일이 있으면 자동으로 컨텍스트로 읽어들인다(클로드 코드의 CLAUDE.md와 같은 역할이다).

 

자주 쓰는 명령어 — 외워두면 편하다

 

# 비대화형 모드 (스크립트에 박아넣기 좋음)
pi -p "이 파일에서 버그 찾아줘"

# 가장 최근 세션 이어서 진행
pi -c

# 특정 모델로 시작
pi --model openai/gpt-4o

# 도구 제한 (읽기랑 grep만 쓰게)
pi --tools read,grep

# 스킬 호출
pi /skill:name

 

키보드 단축키 — 손에 익으면 광속이다

 

단축키	동작
Ctrl+C 두 번	종료
Ctrl+L	모델 선택기
Shift+Tab	thinking level 순환
Alt+Enter	메시지 큐에 후속 추가
Enter	실행 중 에이전트에 끼어들기

 

특히 Ctrl+L로 모델을 즉시 바꾸는 것과, 실행 중간에 Enter로 끼어드는 기능이 진짜 편하다.

 

사용할만한가?

 

기본기는 위에서 모두 다뤘고, 좀 더 들어간 기능 중 진짜 가치 있는 것만의 내용이다.

 

AGENTS.md / CLAUDE.md로 프로젝트 컨텍스트 주입

 

프로젝트 루트에 AGENTS.md 파일을 만들고 거기에 프로젝트 규칙, 코딩 컨벤션, 자주 쓰는 명령어 같은 것을 적어두면 pi가 매번 읽는다. 클로드 코드의 CLAUDE.md와 똑같은 역할이다. 사실 pi는 두 파일 모두 인식한다. 호환성 확보용이다.

 

SYSTEM.md로 시스템 프롬프트 통째로 교체하기

 

이것이 pi의 진짜 차별화 포인트다. 프로젝트 루트 .pi/SYSTEM.md(프로젝트 단위) 또는 ~/.pi/agent/SYSTEM.md(전역)에 파일을 만들면 시스템 프롬프트 자체를 갈아끼울 수 있다. 200토큰짜리가 기본인데, 거기다 본인 워크플로우에 맞게 700토큰짜리를 작성해 박아넣어도 클로드 코드의 1만 토큰보다 훨씬 가볍다. 자기 손에 맞게 하네스를 깎아 쓴다는 철학이 여기서 드러난다.

 

TypeScript 익스텐션으로 직접 도구 만들기

 

새 도구가 필요하면 TypeScript로 직접 만들면 된다. 마켓플레이스 같은 것을 거치지 않고, 본인 프로젝트에 .ts 파일 하나를 추가하면 끝이다. 보안 측면에서는 임의 코드 실행이라 위험하긴 한데, 그만큼 자유도가 높다.

 

비대화형 모드 — CI/CD에 박아넣기

 

pi -p "최근 커밋 diff 보고 변경 요약 한국어로 출력해줘"

 

위처럼 -p 옵션으로 비대화형 모드를 돌리면 결과를 stdout으로 뱉는다. GitHub Actions, CI 파이프라인, cron job에 박아넣기 좋다. JSON 출력 옵션도 있어서 후처리도 쉽다.

 

Tree 구조 세션과 GitHub gist 공유

 

세션이 tree 구조라서, 한 대화에서 분기를 떠서 다른 시도를 해보고 다시 원래로 돌아올 수 있다. 그리고 세션을 GitHub gist로 통째로 공유할 수도 있다. 디버깅 도움을 요청할 때 "이 세션 통째로 보내드릴게요"가 가능한 것이다.

 

솔직히 단점도 있다 — 모든 것이 장밋빛은 아니다

 

칭찬만 늘어놓는 것은 무책임하니 단점도 박는다.

 

익스텐션은 임의 코드 실행이다 — 보안에 신경 써야 한다

 

TypeScript 익스텐션이 자유도가 높은 만큼 보안 책임도 본인에게 있다. 모르는 사람이 만든 익스텐션을 막 깔면 안 된다. 클로드 코드처럼 권한 팝업으로 막아주는 장치가 없으니, 익스텐션 코드는 본인이 한 번 훑어보고 써야 한다.

 

클로드 코드처럼 친절하지 않다 — 자기 세팅이 필수다

 

처음 설치하면 "어, 끝?" 싶을 정도로 휑하다. todo 트래커도 없고, plan mode도 없으며, MCP로 연결한 외부 도구도 없다. 본인이 워크플로우를 짜고 SYSTEM.md를 다듬고 AGENTS.md를 채워넣어야 진가가 나온다. AI 코딩을 처음 써보는 사람에게는 부담될 수 있다.

 

한국어 자료가 아직 적다

 

이 글이 그래서 쓰인 것이다. blog.peaknine.io 정도를 제외하면 본격 한국어 가이드가 거의 없다. 영어 자료(공식 docs, Mario 블로그, Armin 블로그)는 풍부하니 영어 거부감이 없으면 별 문제가 아닐 수도 있다.

 

누가 갈아타면 좋은가 — 추천/비추 매트릭스

 

이를 4사분면으로 정리해봤다.

 

구분	솔로 개발	팀 개발
**시니어**	★★★ 추천: 자기 워크플로우 명확하면 최적	★★ 보류: 팀 표준화 비용 고려
**주니어**	★ 비추: 클로드 코드부터 시작 권장	★ 비추: 너무 많은 자유는 독이다

 

추천: 자기 워크플로우가 명확한 시니어 솔로 개발자

 

자기가 무엇을 하고 싶은지 명확하고, 클로드 코드의 자동 기능들이 오히려 방해된다고 느끼는 사람에게 최적이다. 컨텍스트를 절약하면서 본인 도구를 만들어 쓰는 것이 즐거운 사람이다.

 

비추: AI 코딩을 처음 써보는 사람

 

이것은 솔직히 비추한다. 클로드 코드나 Cursor 같은 친절한 도구로 일단 감을 잡고, 그 다음에 "이게 너무 무거운데?" 싶을 때 pi로 갈아타는 것이 순서다.

 

보류: 팀 단위로 쓸 때

 

팀에서 표준화하려면 익스텐션, SYSTEM.md, AGENTS.md를 모두 합의해야 한다. 그 비용이 만만치 않다. 작은 팀이면 가능하지만, 큰 조직이면 클로드 코드처럼 표준화된 도구가 차라리 낫다.

 

미니멀이 진짜 미덕인 시대가 온 것이다

 

정리하면 이렇다:

 

1. pi는 1만 토큰짜리 시스템 프롬프트가 200토큰으로 줄어드는 미니멀 코딩 하네스다 — Mario Zechner가 만들고 Armin Ronacher가 이끄는 Earendil이 인수했다.
2. 기본 도구 4개(read, write, edit, bash)에 MCP·sub-agents·plan mode를 모두 뺐다 — 의도적으로. 빼야 가볍고, 가벼워야 그 위에 올릴 수 있다.
3. 5분 안에 깔고 돌릴 수 있다 — curl 한 줄, 또는 npm 한 줄. Anthropic 구독자라면 추가 비용 없이 /login으로 바로 쓸 수 있다.

 

처음에 비유로 시작했으니 마무리도 비유로 하자면, pi는 "엔진과 핸들만 있는 카트"라고 했다. 정확한 표현이다. 다만 그 카트가 본인 손에 익으면 1톤짜리 SUV보다 빠를 수 있다는 것이 핵심이다. 모든 사람에게 추천하는 도구는 아니지만, "내가 무엇을 원하는지 정확히 아는 개발자에게는 신무기" 다.

 

한 번은 깔아볼 만하다. 안 맞으면 npm uninstall -g @earendil-works/pi-coding-agent 한 줄이면 사라진다. 잃을 것이 없다.

 

pi 코딩 에이전트를 더 깊이 파보고 싶다면 pi 공식 사이트와 GitHub 저장소부터 시작하기를 추천한다. Armin Ronacher 인수 발표 글도 읽어두면 이 프로젝트가 어디로 가는지 감을 잡기 좋다. 다음에는 pi vs Codex 비교나 pi 익스텐션을 직접 만드는 법을 정리해서 올릴 예정이다. 그때 다시 보자.