Pi-Bolt가 코딩 에이전트 Pi를 네이티브 실행 파일로 제공한다

Pi-Bolt 저장소는 코딩 에이전트 Pi를 미리 네이티브 코드로 컴파일해 단일 실행 파일로 제공하는 프로젝트다. Linux x86-64·ARM64, Apple silicon을 탑재한 macOS, Windows x64를 지원하며, 기본 빌드는 JIT 컴파일러나 Node.js, Bun 없이 실행된다. Pi-Bolt 제작자는 Pi의 기존 명령어·세션·설정·제공자·확장 기능을 그대로 쓸 수 있고, Pi를 Node 24에서 실행한 경우보다 일부 작업에서 CPU 사용량과 메모리가 적고 처리 시간이 짧다고 밝혔다.

Pi-Bolt 1.0.0과 npm에 공개된 Pi 1.4.0을 비교한 수치는 Linux x86-64에서 400KB 파일 쓰기 120배 빠름, 긴 답변 스트리밍 중 CPU 사용량 8배 적음, 세션의 40번째 프롬프트까지 진행한 뒤 메모리 4.5배 적음이다. 아래 결과는 제작자가 공개한 벤치마크이며, 실행 환경과 측정 조건은 각 결과와 함께 봐야 한다.

설치와 실행

Linux, macOS, Android의 Termux에서는 설치 스크립트를 실행한다.

curl -fsSL https://pi-bolt.opensec.in/install.sh | sh

Windows PowerShell에서는 다음 명령을 사용한다.

irm https://pi-bolt.opensec.in/install.ps1 | iex

명령 프롬프트에서 설치하려면 다음과 같이 실행한다.

powershell -c "irm https://pi-bolt.opensec.in/install.ps1 | iex"

npm이나 Bun을 이용해 설치하거나, Arch Linux의 커뮤니티 AUR 패키지를 사용할 수도 있다.

npm install -g --allow-scripts=pi-bolt pi-bolt
bun add -g --trust pi-bolt
paru -S pi-bolt-avx2-bin-release-git

AUR 패키지 pi-bolt-avx2-bin-release-git은 서명을 확인하는 x86-64 AVX2 빌드다. 설치 후 프로젝트 디렉터리에서 pi-bolt를 실행한다. 업데이트, 직전 빌드로 되돌리기, 베타 채널 사용은 다음 명령으로 처리한다.

pi-bolt # start
pi-bolt update # install the latest release
pi-bolt update --rollback # put back the build it replaced
pi-bolt update --channel beta # take pre-releases too

Pi를 처음 사용하는 경우 /login으로 제공자에 연결한다. 기존 Pi 설정인 ~/.pi/agent를 그대로 사용하며, Pi와 나란히 설치해 각각 pi와 pi-bolt로 실행할 수 있다. 설치 프로그램을 다시 실행하면 업데이트·재설치·제거를 할 수 있다.

설치 프로그램은 릴리스 서명을 확인하고 OpenSec의 선택형 확장 세 가지를 제공한다. opensec-pi-subagents는 별도 세션의 전문 에이전트, 병렬 작업 흐름, 예약 작업을 제공한다(npm). opensec-pi-todo는 편집기 위에 실시간 패널로 표시되는 모델용 할 일 목록이다(npm). opensec-pi-fff는 기본 빌드에서 전체 속도로 사용할 수 있는 pi-fff의 빠른 퍼지 검색, grep, @ 멘션 기능을 제공한다(npm).

확장 기능과 JIT 빌드

기본 빌드에서는 Pi 자체 코드가 기계어로 컴파일되지만, 실행 중 불러오는 확장 기능은 인터프리터로 실행된다. 가벼운 확장 기능에는 영향이 없다고 프로젝트는 설명한다. 검색·파싱처럼 연산량이 큰 확장 기능이나 bun:ffi를 사용하는 확장 기능에는 JIT 빌드를 설치할 수 있다. Pi 본체는 계속 컴파일된 상태로 실행되며, 제작자는 이 빌드가 기본 빌드와 약 5% 이내 차이라고 설명한다.

# macOS, Linux ARM64, Termux
curl -fsSL https://pi-bolt.opensec.in/install.sh | PIBOLT_VARIANT=arm64-jit sh
# Linux x86-64
curl -fsSL https://pi-bolt.opensec.in/install.sh | PIBOLT_VARIANT=x64-jit sh

Windows에서는 PowerShell 설치 명령을 실행하기 전에 $env:PIBOLT_VARIANT = "x64-jit"를 설정한다. npm을 쓰는 경우 셸 프로필에 PIBOLT_VARIANT를 설정해 매 실행 때 적용되게 한다. pi-bolt --version 출력 끝에 JIT on이 표시되며, 이후 pi-bolt update도 선택한 빌드를 유지한다. 기본 빌드에서 bun:ffi를 통해 네이티브 라이브러리를 호출하는 등 JIT가 필요한 확장 기능을 실행하면, 오류 메시지에 확장 기능 이름과 JIT 빌드로 바꾸는 명령이 표시된다.

수동 설치는 최신 릴리스에서 빌드를 내려받아 SHA256SUMS와 대조하고 압축을 푼 뒤 실행한다. Linux와 macOS에서는 ./pi, Windows에서는 pi-bolt.exe를 실행한다. 다운로드 파일은 대상 플랫폼과 조건에 따라 다르다.

• pi-bolt-linux-x64.tar.xz: AVX2를 지원하는 Linux CPU(Intel Haswell, AMD Zen 및 이후 제품)
• pi-bolt-linux-x64-baseline.tar.xz: 모든 x86-64 Linux CPU
• pi-bolt-linux-arm64.tar.xz: 64비트 ARM Linux CPU(Raspberry Pi 3 이후 제품, AWS Graviton, Ampere)
• pi-bolt-darwin-arm64.tar.xz: Apple silicon을 탑재한 macOS
• pi-bolt-win32-x64.zip: Windows x64. AVX2 CPU에서는 컴파일된 코드로, 그 밖의 CPU에서는 바이트코드로 실행

-jit 빌드는 실행 중 불러온 플러그인을 많이 사용하는 경우를 위한 것이다. 런타임 및 킷 아카이브는 pi-bolt compile이 사용하는 파일이다. 플러그인 컴파일 안내를 참조할 수 있다.

Android에서는 Google Play가 아닌 F-Droid 또는 GitHub에서 Termux를 설치하고 일반 설치 명령을 실행한다. Google Play 버전에는 glibc 패키지가 없다. Pi-Bolt는 glibc 프로그램이고 Android의 libc는 glibc가 아니므로, 설치 프로그램은 먼저 사용자에게 확인한 뒤 pkg install glibc-repo && pkg install glibc로 Termux의 glibc를 설치하고 실행 파일 로더를 설정한다. 이어 pi-bolt를 $PREFIX/bin에 연결한다. 작은 실행기인 pi-bolt는 Android 시간대를 사용하고 Termux의 LD_PRELOAD를 적용하지 않은 채 Pi-Bolt를 시작한다. 이는 Android libc 라이브러리를 glibc가 불러올 수 없기 때문이다. Pi-Bolt가 시작하는 프로그램에는 해당 설정이 다시 적용된다. 설치 프로그램은 Termux의 resolv.conf와 hosts를 $PREFIX/glibc/etc에 복사하며, Termux의 glibc가 이 파일을 읽는다. 자세한 내용은 Android·Termux 안내에 있다.

요구 사항은 Linux x86-64 또는 ARM64의 glibc 2.17 이상이다. Ubuntu 20.04 이상, Debian 11 이상, RHEL/Rocky 8 이상, Amazon Linux 2, 64비트 Raspberry Pi OS 등이 해당한다. musl은 지원하지 않는다. Android는 64비트 ARM과 Android 7 이상, Termux가 필요하다. macOS는 Apple silicon과 macOS 13 이상이 필요하며 설치 프로그램이나 npm으로 설치한다(문제 해결 안내). Windows는 x64에서 Windows 10(1809) 이상 또는 Windows 11을 요구하며, 설치 프로그램이나 npm으로 설치한다(Windows 문제 해결). Windows ARM64에서는 Windows 11의 x64 에뮬레이션으로 x64 빌드를 실행한다.

기능과 설정

pi-bolt --acp는 Pi 설정·확장 기능·스킬·세션을 사용해 Zed, JetBrains IDE, VS Code, Neovim 등 ACP 편집기의 에이전트 패널에서 Pi-Bolt를 실행한다. 설정 안내를 볼 수 있다. pi-bolt --mcp는 MCP 서버로 동작한다. 다른 에이전트가 prompt 도구로 작업을 전달하고, 이후 호출에서 세션을 이어갈 수 있다(설정 안내).

기본 제공되는 grep과 find 도구는 별도 설치 없이 프로세스 안에서 검색하고 .gitignore를 따른다. opensec-pi-fff 또는 @ff-labs/pi-fff를 불러오면 대신 FFF의 검색 도구를 사용한다. pi-bolt compile은 릴리스에 포함된 자체 컴파일러로 이 컴퓨터에 설치된 확장 기능을 Pi-Bolt에 컴파일한다(Linux와 macOS). 컴파일된 확장 기능은 기계어로 실행되며, pi-bolt update는 확장 기능을 새 릴리스에 다시 컴파일한다(플러그인 안내).

pi-bolt doctor는 설치 빌드와 설치 방식, 릴리스 서명 확인 여부, 컴파일·실행 시 로드·로드 실패 상태인 확장 기능, Pi의 packages와 piBolt.packages 차이, Herdr와 편집기 설정, PATH 앞쪽에 다른 pi-bolt가 있는 문제 등을 일반 텍스트로 출력한다. 이 보고서는 이슈에 붙여넣도록 만든 것이다. 키나 토큰은 출력하지 않고 홈 디렉터리는 ~로 표시한다. pi-bolt doctor --offline은 릴리스 서명과 새 버전 확인을 생략한다. 업데이트는 pi-bolt update로 설치하며 --rollback으로 교체 전 빌드로 되돌릴 수 있다.

Herdr 패널에는 Pi-Bolt가 pi-bolt라는 이름으로 표시되며 대기·작업 중·차단 상태를 보여준다. Herdr를 재시작하면 같은 패널에서 같은 대화를 다시 연다. 별도 설치는 필요 없으며, 설정의 extensions에 "-builtin:herdr"를 넣으면 기능을 끌 수 있다. 세션 복원에는 Herdr 0.9.2 이상이 필요하다. Pi-Bolt에서 다른 에이전트를 Herdr 패널에 띄우려면 다음과 같이 pi-herdr를 설치한다.

pi-bolt install npm:@andrewjacop/pi-herdr

Pi와 Pi-Bolt는 ~/.pi/agent 디렉터리와 공유 packages 목록을 사용한다. 일반적인 pi-bolt install과 pi-bolt remove는 Pi와 마찬가지로 공유 목록을 바꾸고, Pi-Bolt 전용 목록 항목은 제거한다. 따라서 두 프로그램은 공유 목록에 선언된 패키지를 함께 불러온다. --pi-bolt를 붙이면 Pi-Bolt의 덮어쓰기 설정만 바꾼다.

pi-bolt install --pi-bolt npm:@example/bolt-tools
pi-bolt remove --pi-bolt npm:@example/shared-tools

piBolt.packages는 공유 목록을 확장한다. -source 항목은 Pi 설정을 바꾸지 않고 Pi-Bolt에서 상속된 패키지를 제외한다. 다른 공유 패키지는 계속 상속된다. 자세한 내용은 설정 문서에 있다.

{
 "packages": ["npm:@juicesharp/rpiv-todo"],
 "piBolt": { "packages": ["-npm:@juicesharp/rpiv-todo", "npm:opensec-pi-todo"] }
}

Zed의 settings.json에서는 다음처럼 등록할 수 있다. 다른 편집기는 ACP 문서를 참조한다.

"agent_servers": {
 "Pi-Bolt": { "type": "custom", "command": "/full/path/to/pi-bolt", "args": ["--acp"], "env": {} }
}

Claude Code에서는 다음 명령으로 MCP 서버를 등록한다. 다른 클라이언트는 MCP 문서에 안내돼 있다.

claude mcp add pi-bolt -- /full/path/to/pi-bolt --mcp

벤치마크

아래는 Pi-Bolt 1.0.0과 npm에 공개된 Pi 1.4.0을 비교한 프로젝트의 결과다. Pi는 기본 Bun 1.4.4 또는 Node 24로 실행했다. 세 프로그램은 같은 로컬 모델을 대상으로 같은 작업을 수행했으며, 수치가 낮을수록 좋다.

Linux 측정에는 GitHub 실행기를 사용했고 CPU를 하나로 고정했다. Windows 실행기는 코어 2개를 사용했으며 메모리는 작업 집합 기준이다. macOS는 Apple M5에서 측정했고 CPU를 고정하지 않았다. 원시 데이터와 측정 방법은 Node 22 관련 결과와 함께 공개돼 있다. PiG 0.5.1과의 비교는 Pi-Bolt와 PiG 비교 결과, 나머지 결과와 방법은 벤치마크 문서에 있다.

구현과 프로젝트 자료

프로젝트 설명에 따르면 빌드 과정은 네 단계다. Bun이 Pi를 묶어 JavaScriptCore 바이트코드로 컴파일한다. 사전 컴파일러가 JavaScriptCore 최상위 JIT의 백엔드인 B3를 통해 각 함수를 최적화된 x86-64 또는 ARM64 기계어로 바꾼다. 이미 로드된 Pi 모듈을 담은 힙을 실행 파일에 포함해 시작할 때 매핑하고, 학습 프로필로 코드 순서를 정해 시작 과정에서 접근하는 페이지 수를 줄인다.

컴파일러는 oven-sh/WebKit#743을 기반으로 한다. Pi-Bolt는 이를 x86-64와 macOS로 포팅하고 자체 코드 생성 및 런타임 작업을 더했다고 설명한다(아키텍처 문서). packages/에는 sources.json에 적힌 Pi 릴리스와 Pi-Bolt 변경 사항이 들어가며, 엔진 변경은 patches/에 있다.

문서는 아키텍처, 소스 빌드와 테스트, 벤치마크, 플러그인, 편집기 설정, 다른 에이전트 연동, 문제 해결, 릴리스로 나뉜다.

소스에서 빌드할 때는 저장소를 복제하고 런타임과 Pi를 준비한 뒤 빌드 및 엔진 테스트를 실행한다.

git clone https://github.com/opensec-git/Pi-Bolt.git && cd Pi-Bolt
scripts/fetch-runtime.sh # the released Pi-Bolt runtime (or build it: docs/BUILDING.md)
scripts/prepare-pi.sh # builds the Pi in this repository
scripts/build-pi.sh # out/pi-bolt/pi
tests/aot/run.sh # engine tests

버그 보고, 다른 하드웨어에서의 벤치마크와 수정 제안은 기여 안내를 따른다. 보안 문제는 보안 안내에 따라 비공개로 보고한다.

라이선스는 MIT다. 릴리스 실행 파일에는 Bun(MIT), JavaScriptCore(LGPL-2.0 및 BSD), ICU(Unicode License), Pi(MIT)가 포함된다. 자세한 내용은 제3자 고지를 참조한다. Pi-Bolt는 Pi의 독립 포크이며 Pi 제작자나 Oven과 제휴하지 않았다. Pi는 Mario Zechner와 기여자들이, Bun은 Oven이 만들었다.