pi

새 기여자의 새 이슈와 PR은 기본적으로 자동으로 닫힙니다. 메인테이너는 자동으로 닫힌 이슈를 매일 검토합니다. CONTRIBUTING.md를 참고하세요.

Pi
Pi는 여러분이 직접 자신만의 것으로 만들 수 있는 최소한의 확장 가능한 에이전트 하네스입니다.

워크플로우를 Pi에 맞추지 말고, Pi를 여러분의 워크플로우에 맞추세요. 확장 , 스킬 , 프롬프트 템플릿 , 테마 로 Pi를 커스터마이즈하세요. 이를 Pi 패키지로 묶어 npm이나 git을 통해 공유할 수 있습니다.

Pi는 강력한 기본값을 제공하지만 서브 에이전트나 플랜 모드 같은 기능은 생략합니다. 원하는 것을 Pi에게 만들어 달라고 하거나, 원하는 방식으로 구현한 패키지를 설치하세요.

Pi를 대화형 으로 사용하거나, print 또는 JSON 모드 로 자동화하거나, RPC로 제어하거나, Pi TypeScript SDK로 앱을 만들 수 있습니다. 실제 사례는 OpenClaw를 참고하세요.

시작하기
명령줄 인터페이스를 설치하세요:

curl -fsSL https://pi.dev/install.sh | sh
Windows에서는:

powershell -c " irm https://pi.dev/install.ps1 | iex "
설치 프로그램은 모든 의존성을 고정하며 pi update 로 Pi를 업데이트합니다. 또는 전이 의존성을 고정하지 않는 npm으로 직접 설치할 수도 있습니다:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Pi는 Node.js 22.19 이상이 필요합니다. macOS, Linux, Windows 설치 프로그램이 필요 시 이를 설치할 수 있습니다. Pi는 일반적인 npm 설치에 의존성 라이프사이클 스크립트를 필요로 하지 않습니다.

작업할 디렉터리에서 Pi를 시작하세요:

cd /path/to/project
pi
내장 AI 제공자를 사용하려면 Pi 안에서 /login 을 실행하여 구독 또는 API 키를 연결하세요. 그런 다음 Pi에게 작업을 지시하세요.

전체 설정 및 사용 방법은 문서를 참고하거나, 데모는 pi.dev를 방문하세요.

Nix로 실행하기
nix run github:earendil-works/pi/stable
stable 은 최신 릴리스를 가리킵니다. nix profile add github:earendil-works/pi/stable 로 설치하고 nix profile upgrade pi 로 업데이트하세요. github:earendil-works/pi/v1.0.0 같은 릴리스 태그를 사용해 버전을 고정하거나, github:earendil-works/pi 를 사용해 main 의 미출시 변경 사항을 사용할 수 있습니다. Nix는 소스에서 Pi를 빌드합니다.

Linux와 macOS에서 ARM64와 x86-64를 지원합니다. nix build . 또는 nix run . 을 사용해 체크아웃을 빌드하거나 실행하세요.

Nix 빌드는 오프라인으로 진행되므로, 번들된 모델 데이터는 nix/model-catalog.json 에 고정된 pi.dev 모델 카탈로그 리비전에서 가져옵니다. 런타임에는 Pi가 평소처럼 pi.dev의 최신 카탈로그 데이터를 덮어씁니다. Nix 워크플로우는 고정된 리비전이 체크아웃과 더 이상 일치하지 않을 때(예: 제공자가 추가되거나 새로운 모델 유형이 생겼을 때) main 의 고정을 교체합니다. 수동으로 갱신하려면:

npm run update:model-catalog-pin
패키지
이 모노레포는 Pi CLI와 이를 지원하는 라이브러리를 포함합니다.

패키지
설명

@earendil-works/chord
핫 리로드 가능한 플러그인, 계약, 복제 상태, JSON 링크를 통한 RPC를 위한 타입 지정 호스트 런타임

@earendil-works/pi-telemetry
벤더 중립적 텔레메트리 계약, 참조 어댑터, 적합성 테스트, 타입 지정 스키마

@earendil-works/pi-ai
통합 멀티 제공자 LLM API (OpenAI, Anthropic, Google 등)

@earendil-works/pi-durable
내구성 있는 대화, 작업, 문서 런타임

@earendil-works/pi-agent-core
도구 호출과 상태 관리를 갖춘 에이전트 런타임

@earendil-works/pi-coding-agent
대화형 코딩 에이전트 CLI

@earendil-works/pi-tui
차분 렌더링을 지원하는 터미널 UI 라이브러리

Slack/채팅 자동화와 워크플로우는 earendil-works/pi-chat 을 참고하세요.

권한 및 컨테이너화
Pi는 파일시스템, 프로세스, 네트워크, 자격 증명 접근을 제한하는 내장 권한 시스템을 포함하지 않습니다. 기본적으로 Pi를 실행한 사용자와 프로세스의 권한으로 실행됩니다.

더 강력한 경계가 필요하다면 Pi를 컨테이너화하거나 샌드박스화하세요. 세 가지 패턴은 packages/coding-agent/docs/containerization.md를 참고하세요:

Gondolin 확장 : pi와 제공자 인증은 호스트에 두고 내장 도구와 ! 명령을 로컬 Linux 마이크로 VM으로 라우팅합니다.
일반 Docker : 간단한 격리를 위해 전체 pi 프로세스를 로컬 컨테이너에서 실행합니다.
OpenShell : 정책으로 제어되는 샌드박스에서 전체 pi 프로세스를 실행합니다.

기여하기
기여 가이드라인은 CONTRIBUTING.md를, 프로젝트별 규칙(사람과 에이전트 모두 해당)은 AGENTS.md를 참고하세요. Pi의 장기 계획은 RFCs 에서도 확인할 수 있습니다.

개발
npm install --ignore-scripts # 라이프사이클 스크립트 없이 모든 의존성 설치
npm run build # 모델 데이터를 갱신한 후 모든 패키지 빌드
npm run build:offline # 네트워크 접근 없이 기존 모델 데이터로 재빌드
npm run check # 린트, 포맷, 타입 검사
./test.sh # 테스트 실행 (API 키 없으면 LLM 의존 테스트 건너뜀)
./pi-test.sh # 소스에서 pi 실행 (어느 디렉터리에서든 실행 가능)
모노레포 외부에서 로컬 패키지 사용하기
모든 공개 패키지를 하나의 일관된 로컬 아티팩트 세트로 빌드하세요:

npm run pack:packages -- --out .artifacts/pi-packages
이 명령은 pi-ai 를 빌드하기 전에 모델 데이터를 갱신합니다. 모델 데이터가
이미 준비되어 있을 때 네트워크 접근을 피하려면 --offline-model-data 를 전달하세요.

그런 다음 외부 프로젝트가 하나의 패키지를 사용하고 모든 Pi 의존성을
동일한 아티팩트 세트에서 해석하도록 구성하세요. 기본값은 npm입니다:

node scripts/use-local-packages.mjs \
--manifest .artifacts/pi-packages/manifest.json \
--consumer ../my-project \
--package @earendil-works/pi-durable \
--package @earendil-works/pi-agent-core
cd ../my-project
npm install --ignore-scripts
pnpm 프로젝트의 경우 --consumer 를 워크스페이스 루트로 지정하세요:

node scripts/use-local-packages.mjs \
--manifest .artifacts/pi-packages/manifest.json \
--consumer ../my-project \
--package @earendil-works/pi-agent-core \
--package-manager pnpm
cd ../my-project
pnpm install --ignore-scripts
각 직접 의존성마다 --package 를 반복하세요. 이 명령은 소비자의
package.json 을 콘텐츠 주소 지정 방식의 로컬 file: 참조로 업데이트합니다.
전이 오버라이드는 npm의 경우 package.json 에, pnpm의 경우 pnpm-workspace.yaml 에
기록됩니다. 소비자를 설치하거나 업데이트하는 동안 아티팩트 디렉터리를
사용 가능한 상태로 유지하세요. Pi 소스를 변경한 후에는 두 명령을 모두 다시 실행하세요.

릴리스 소스에서 독립 실행형 바이너리 빌드하기
GitHub 릴리스에는 릴리스의 SHA256SUMS 파일로 검증되는 버전 지정 소스 아카이브가 포함됩니다. 이를 추출하고 공식 독립 실행형 바이너리에 사용된 것과 동일한 빌드 스크립트를 실행하세요:

VERSION= " <release-version> "
tar -xzf " pi- ${VERSION} -source.tar.gz "
cd " pi- ${VERSION} "
./scripts/build-binaries.sh --offline-model-data --platform linux-x64 --out " $PWD /out "
아카이브에는 릴리스 모델 데이터와 네이티브 프리빌드가 포함됩니다. --offline-model-data 는 제공자 카탈로그를 갱신하지 않고 해당 모델 데이터를 사용합니다. 스크립트는 의존성을 설치하고 런타임 자산과 함께 실행 파일을 빌드합니다. 의존성이 이미 제공되어 있다면 --skip-install 을 전달하세요.

공급망 강화
우리는 npm 의존성 변경을 검토된 코드 변경으로 취급합니다.

직접 외부 의존성은 정확한 버전으로 고정됩니다. 내부 워크스페이스 패키지는 버전 범위를 유지합니다.
.npmrc 는 save-exact=true 와 min-release-age=2 를 설정하여 npm 해석 중 당일 의존성 릴리스를 피합니다.
package-lock.json 이 의존성의 기준입니다. PI_ALLOW_LOCKFILE_CHANGE=1 이 설정되지 않은 한 커밋 전 훅이 실수로 인한 lockfile 커밋을 차단합니다.
npm run check 는 고정된 직접 의존성, 네이티브 TypeScript 임포트 호환성, 생성된 coding-agent 설치 lock을 검증합니다.
pi.dev 설치 프로그램은 루트 lockfile에서 생성된 packages/coding-agent/install-lock/ 에서 설치하여 전이 의존성을 고정합니다. npm 패키지는 전이 의존성을 고정하지 않습니다.
로컬 릴리스 스모크 테스트와 npm 게시는 동일한 tarball 패커를 사용합니다. npm은 워크스페이스 디렉터리를 다시 패킹하지 않고 검증된 tarball을 게시합니다.
로컬 릴리스 설치, 문서화된 npm 설치, pi update --self 는 지원되는 경우 --ignore-scripts 를 사용합니다.
CI는 npm ci --ignore-scripts 로 설치하며, 예약된 GitHub 워크플로우가 npm audit --omit=dev 와 npm audit signatures --omit=dev 를 실행합니다.
설치 lock 생성에는 의존성 라이프사이클 스크립트에 대한 명시적 허용 목록이 있습니다. 새로운 라이프사이클 스크립트 의존성은 검토될 때까지 검사를 통과하지 못합니다.

OSS 코딩 에이전트 세션 공유하기
오픈 소스 작업에 Pi나 다른 코딩 에이전트를 사용한다면 세션을 공유해 주세요.

공개 OSS 세션 데이터는 장난감 벤치마크 대신 실제 작업, 도구 사용, 실패, 수정을 통해 코딩 에이전트를 개선하는 데 도움이 됩니다.

전체 설명은 X의 이 게시물 을 참고하세요.

세션을 게시하려면 badlogic/pi-share-hf 를 사용하세요. 설정 방법은 README.md를 참고하세요. 필요한 것은 Hugging Face 계정, Hugging Face CLI, pi-share-hf 뿐입니다.

제 pi-mono 세션을 게시하는 방법을 보여주는 이 영상 도 시청할 수 있습니다.

저는 제 pi-mono 작업 세션을 정기적으로 여기에 게시합니다:

Hugging Face의 badlogicgames/pi-mono

라이선스
MIT

pi.dev 도메인을 흔쾌히 기증해 주신

exe.dev