Pi는 earendil-works/pi 프로젝트가 만드는 터미널 기반 코딩 에이전트입니다. 작업 폴더와 목표를 주면 파일을 읽고, 검색하고, 명령을 실행하고, 코드를 수정해서 여러 단계의 작업을 스스로 처리합니다. 소프트웨어 개발뿐 아니라 조사 노트, 글쓰기, 데이터 파일 정리 같은 일반 작업에도 쓸 수 있습니다.

Pi가 다른 에이전트 도구와 구별되는 지점은 "하네스(harness)"라는 자기 규정입니다. Pi는 에이전트 루프, 세션 저장, 도구 실행이라는 뼈대만 탄탄하게 제공하고, 그 위에 얹는 기능은 사용자가 기호에 맞게 직접 조립하도록 설계했습니다.

최소주의 설계 철학

Pi는 서브 에이전트나 계획 모드(plan mode) 같은 기능이 기본으로 들어 있지 않습니다. 유지 보수 팀이 모든 사용자의 워크플로를 대신 정할 수 없다고 보기 때문입니다. 대신 이렇게 안내합니다.

• 필요한 기능이 없으면 Pi에게 직접 만들어 달라고 시키거나,
• 다른 사람이 만든 Pi 패키지를 npm이나 git으로 설치해서 자기 방식으로 쓰세요.

이렇게 직접 맞춰 쓸 수 있는 수단이 네 가지입니다.

수단	역할
확장(Extension)	TypeScript 모듈로 도구·명령·이벤트 처리 추가
스킬(Skill)	작업별 지침과 보조 파일을 필요할 때만 로드
프롬프트 템플릿	자주 쓰는 프롬프트를 /명령으로 재사용
테마	터미널 색 조합 변경

이 자원들은 Pi 패키지로 묶어 npm 또는 git으로 공유할 수 있습니다. "Pi에 맞추지 말고 Pi를 당신의 워크플로에 맞추라"는 것이 프로젝트의 슬로건입니다.

##monorepo 구성

저장소는 Pi CLI와 그 위에 얹히는 라이브러리를 하나의 monorepo로 관리합니다.

패키지	설명
@earendil-works/pi-coding-agent	대화형 코딩 에이전트 CLI
@earendil-works/pi-agent-core	도구 호출과 상태 관리가 있는 에이전트 런타임
@earendil-works/pi-ai	OpenAI·Anthropic·Google 등을 묶은 통합 LLM API
@earendil-works/pi-tui	차등(differential) 렌더링 터미널 UI 라이브러리
@earendil-works/chord	프로세스 경계를 넘는 오브젝트 런타임
@earendil-works/pi-durable	지속형 대화·작업·문서 런타임
@earendil-works/pi-telemetry	벤더 중립적 텔레메트리 계약

CLI는 이 위에서 동작하므로, 같은 엔진을 SDK로 앱에 내장하거나 RPC로 프로세스를 제어하는 것도 가능합니다.

네 가지 사용 방식

Pi는 하나의 엔진을 여러 인터페이스로 노출합니다.

1. 대화형(interactive): 터미널에서 pi를 실행해 사람과 함께 작업합니다.
2. print / JSON 모드: pi --print "..."처럼 한 번 실행하고 결과를 받습니다. 스크립트·파이프라인에 맞습니다.
3. RPC 모드: stdin/stdout의 JSONL로 Pi 프로세스를 원격 제어합니다.
4. TypeScript SDK: Node.js/Bun 프로세스 안에서 에이전트 세션을 직접 만들고 제어합니다.

보안 관점: 기본은 "프로세스 권한 그대로"

Pi에는 파일시스템·프로세스·네트워크 접근을 제한하는 내장 권한 시스템이 없습니다. Pi는 이를 실행한 사용자 계정의 권한을 그대로 상속합니다. 대신 경계를 원하면 컨테이너나 샌드박스 안에서 실행하는 방식을 공식 문서에서 안내합니다. Docker에서 전체 프로세스를 격리하거나, micro-VM으로 도구 실행만 격리하는 세 가지 패턴이 문서화되어 있습니다. 이 주제의 안전하게 실행하기 글에서 다시 다룹니다.

시작하기

설치는 짧습니다. macOS·Linux에서는 다음 한 줄입니다.

curl -fsSL https://pi.dev/install.sh | sh

그 다음 작업 폴더로 이동해 pi를 실행하고, /login으로 모델 제공자를 연결하면 바로 첫 작업을 시킬 수 있습니다. 자세한 절차는 설치와 퀵스타트에서 살펴봅니다.