bigfish1913/pi-rust

cargo install rpi-cli
rpi --version

brew tap bigfish1913/tap && brew install rpi # macOS (Apple silicon), Linux
scoop bucket add bigfish1913 https://github.com/bigfish1913/scoop-bucket
scoop install rpi # Windows

git clone https://github.com/bigfish1913/pi-rust.git
cd pi-rust && cargo run -p minimal # 오프라인 에이전트, API 키 필요 없음

$ cargo run -q -p minimal
minimal example: 2 messages after run
- user
...

export ANTHROPIC_API_KEY=... # 또는 OPENAI_API_KEY, 또는 ~/.rpi/agent/models.json
rpi # 대화형 TUI
rpi -p

는 leaf이므로 (rpi-* 의존성 없음) 호스트의 플러그인 계약(`rpi-tools`)뿐만 아니라 환경 변수 이름도 읽어와서, 호스트와 그 플러그인이 ABI를 통해 교환하는 문자열에 대해 의견 불일치가 생기지 않게 합니다. 이 경계는 이름만 기반이며 — 아무것도 연결되거나 호출되지 않습니다. `rpi-extensions`

은 `rpi-plugin-sdk`

와 `rpi-ai`

, 그리고 `/rpi-agent`

까지 포함하여 플러그인을 호스팅하고 도구를 실행합니다. `rpi-cli`는 나머지 여덟 개 모두에 의존하며, 이를 통해 `rpi` 바이너리는 TUI, 하네스(harness), 그리고 플러그인 로더를 한 번에 갖게 됩니다.

| 크레이트 (Crate) | 설명 (What it is) |
|---|---|
| `rpi-telemetry` | No-op 기본값을 가진 Span/이벤트 계약 — 계측(instrumentation)은 선택적이며, 트레이싱이나 OpenTelemetry 백엔드를 끌어오지 않습니다. |
| `rpi-ai` | 제공업체에 구애받지 않는 메시지, 스트리밍 및 도구 스키마 타입; Anthropic + OpenAI와 호환되며 `faux` 제공업체를 지원합니다. |
| `rpi-agent` | 에이전트 루프: `AgentTool`, 이벤트, 훅(hooks), 큐(queues), 취소(cancellation) |
| `rpi-tools` | `read` /`write` /`edit` /`bash` (+ `grep` , `find` , `ls` , `powershell` ) 및 `ExecutionEnv` 시퀀스 (seam) |
| `rpi-harness` | 세션 트리, JSONL 영속성(persistence), 압축(compaction), 충돌 복구(crash recovery), 실행 루프 (run loop) |
| `rpi-tui` | 터미널 UI 기본 요소: 컴포넌트, 레이아웃, 에디터, 트랜스크립트 렌더링 |
| `rpi-cli` | `rpi` 바이너리: TUI, 일회성(one-shot) 및 JSON 모드, 설정(config), 플러그인 로딩 |
| `rpi-plugin-sdk` | 플러그인을 위한 안정적인 `#[repr(C)]` ABI 계약. rpi-* 의존성이 없으며; 기본 `json` 기능 뒤에만 `serde_json`이 있고 이 기능은 끌 수 있습니다. |
| `rpi-extensions` | 호스트 측 플러그인 로더 및 비동기(async)-across-ABI 도구 브릿지 |

모든 크레이트는 자체 README와 docs.rs 페이지를 가지고 있습니다. `crates/rpi-*` 디렉토리와 게시된 크레이트 이름은 동일한 `rpi-` 접두사를 사용합니다.

대부분의 코딩 에이전트는 CLI입니다. `rpi`는 **CLI가 부착된 런타임**이며, 이는 여러분이 무엇을 만들 수 있는지 바꿉니다:

**내장 가능(Embeddable).** 에이전트 루프는 라이브러리입니다. `rpi-agent` + `rpi-ai`}<tool_call|>```json```json_schema: {

자체 프로세스 내에서 에이전트를 실행하고 자체 이벤트 처리 및 출력을 관리할 수 있어 도구를 호출하거나 stdout을 스크래핑할 필요가 없습니다. **테스트 가능(Testable) 오프라인.** 결정론적인 `faux` 프로바이더와 인메모리 실행 환경은 일급 객체이며, 단순히 붙여 넣은 목업이 아닙니다. `rpi-ai`는 실제 HTTP 프로바이더를 `providers` 기능 플래그 뒤에 배치하여, 테스트 스위트가 사용자가 활용하는 경로에 대해 네트워크에 암묵적으로 의존할 수 없게 만듭니다. **내구성(Durable).** 세션은 JSONL 영속성을 가진 트리 구조이며 프레임별 진행 상황을 추적합니다. 도구 호출 중간에 충돌이 발생해도 턴을 잃거나 도구를 중복 실행하는 대신 재개됩니다. **안정적인 경계를 넘나드는 확장성(Extensible across a stable boundary).** 플러그인은 Rust `cdylib`를 기반으로 작성되었으며, 수동으로 작성된 패닉 방지 C ABI와 버전 협상 기능을 갖추고 있습니다. 이 ABI는 컴파일러 및 크레이트 버전의 불일치에도 살아남기 때문에, 확장 기능이 매 릴리스마다 깨지지 않습니다. **하나의 구현, 두 가지 인터페이스(One implementation, two surfaces).** 전역 CLI와 임베디드 에이전트는 동일한 도구를 로드합니다. 따라서 플러그인과 라이브러리 변형을 별도로 유지 관리할 필요가 없습니다.

다른 터미널 코딩 에이전트와의 구조적 차이점. 다른 도구에 대한 사실은 2026년 9월 기준이며 자주 변경되므로, 해당 문서를 확인하세요. 여기서는 `rpi` 열만 유지됩니다.

| rpi | Claude Code | Codex CLI | opencode | aider |
|---|---|---|---|---|
| 언어(Language) | Rust | TypeScript | Rust | TypeScript/Go | Python |
| ... | 

가장 세련된 단일 공급업체 경험을 원한다면, 해당 공급업체의 도구를 사용하세요. `rpi`는 루프를 직접 소유하고 싶은 사람들을 위한 것입니다.

Windows 11 (x86_64), rustc 1.97.1, `--release`에서 측정되었습니다. 두 스크립트 모두 자체 머신에서 다시 빌드하고 재측정해야 합니다.

`sh scripts/bench.sh` — 독립적인 수치:
| 지표(Metric) | 값(Value) |
|---|---|
| 릴리스 바이너리 크기(Release binary size) | 21.8 MiB |
`rpi --version` 벽시계 시간(wall time) | 
~17 ms 중앙값 (median) |
| 에이전트 준비 후 RSS | 12.0 MiB |

`node scripts/bench-vs-pi.mjs --pi <path-to-pi>` — 동일한 머신에서 네이티브 Pi와 비교, 둘 다 오프라인이며 각각 새롭고 격리된 설정 디렉토리를 사용합니다:

| Metric | rpi (Rust) | pi (TypeScript) | Difference |
|---|---|---|---|
| `--version` | 17.5 ms | 169.5 ms | 9.7× faster |
| Cold start | 17.7 ms | 189.5 ms | 10.7× faster |
| RSS at ready | 12.0 MiB | 91.5 MiB | 7.6× smaller |
| Install footprint | 21.8 MiB (one binary) | ~385 MiB (+ ~91 MiB Node) | ~18–22× smaller |

**Cold start**는 스폰(spawn) → 에이전트가 첫 번째 명령을 처리하는 과정: 프로세스 생성 및 전체 초기화 과정을 의미하며, 롤백(teardown)이나 LLM 작업은 제외합니다. rpi의 `--version` (17.5 ms)과 콜드 스타트(17.7 ms)는 사실상 동일하므로, 시작 시간은 초기화가 아닌 프로세스 생성에 의해 결정됩니다. 반면 Pi는 Node 부팅 과정이 지배적입니다.

격리 관련 주의사항: rpi는 `RPI_CODING_AGENT_DIR` / `RPI_OFFLINE`에서 읽고, 네이티브 Pi는 `PI_CODING_AGENT_DIR` / `PI_OFFLINE`에서 읽습니다. 각 항목에 맞는 쌍을 설정하거나, 그렇지 않으면 rpi가 기기의 전역 플러그인을 조용히 로드합니다.

방법, 원시 실행 수치, 그리고 측정되지 않은 것들(LLM 지연 시간, 툴-루프 처리량, 장시간 세션, TUI 프레임 비용)은 `docs/performance/benchmark-vs-pi.md`에 있습니다.

플러그인은 안정적인 `#[repr(C)]` ABI를 가진 Rust `cdylib` 라이브러리입니다. 플러그인은 툴, 프로바이더, 슬래시 명령어, 이벤트 핸들러, 마크다운 렌더러 및 발견된 리소스를 등록할 수 있습니다.

호스트는 프로젝트의 `.rpi/extensions`, 그다음 전역 `~/.rpi/agent/extensions`, 그리고 마지막으로 `--extensions-dir` 순서로 로드합니다.

설치 가능한 확장 기능들은 온라인 카탈로그와 함께 보조 저장소인 `pi-rust/rpi-package`에 있습니다.

`examples/plugin-stub`부터 시작하여 전체 `execute` → `poll` → `cancel` → `destroy` 생명주기를 가진 완전한 플러그인을 사용하고, 스타일적이기보다는 필수적인 안전 규칙은 `docs/extensions/authoring.md`를 참조하세요.

rpi --server # TCP를 통한 헤드리스 에이전트 실행, 인증 토큰 출력
rpi --connect host:port --token T # 로컬 에이전트 리소스가 없는 TUI 클라이언트

The 클라이언트는 제공자(provider), 도구(tools), 확장 기능(extensions) 또는 세션 파일을 보유하지 않습니다. 모든 에이전트 작업은 서버에서 이루어지므로, 어디서든 가벼운 터미널로 강력한 머신을 구동할 수 있습니다. `docs/remote/user-guide.md`를 참조하세요.

| Current release | 0.3.9 (아홉 개의 크레이트가 함께 게시됨) |
| Stability | `rpi-ai`, `rpi-agent`, `rpi-tools`, `rpi-harness`, `rpi-plugin-sdk`가 의도된 안정적인 표면입니다. |
| MSRV | 1.78 |
| ... | 
`rpi`

은 자체 포함형(self-contained) Rust 코딩 에이전트 스택입니다. Node 구성 요소는 필요하지 않으며 로드되지도 않습니다.

기능별로 그룹화된 문서 인덱스부터 시작하세요.

- 사용자 가이드 — 명령어, 설정, 세션, 기술
- 아키텍처 — 크레이트들이 어떻게 함께 작동하는지, 그리고 그 이유
- 에이전트 프로젝트 구축 — 권장 구조
- 확장 작성 — 플러그인 템플릿 및 ABI 규칙
- 원격 모드 — 프로토콜, 토큰, 제한 사항
- 로드맵 · 변경 로그
- docs.rs를 통한 크레이트별 API 문서

이슈(Issues)와 풀 리퀘스트(PRs)는 환영합니다. 빌드/테스트 명령어 및 저장소 레이아웃은 CONTRIBUTING.md부터, 그리고 이미 계획된 내용은 로드맵을 참고하세요. 보안 문제는 공개 이슈가 아닌 SECURITY.md를 통해 처리해야 합니다.

전체 테스트 스위트는 오프라인에서 실행됩니다: `cargo test --workspace --locked`

질문, 아이디어 및 초기 빌드는 다음 두 그룹 중 어느 곳에나 환영합니다:

![]() WeChat — 微信交流群 |
![]() Telegram — t.me/+7YfN4TZPP7Y0M2Q1 |

그룹 초대 코드는 만료됩니다 — WeChat의 경우 며칠마다 순환됩니다. QR 코드가 작동하지 않으면 이슈를 열면 새로 고쳐질 것입니다.

The `rpi-*` 크레이트들은 Rust 네이티브 코딩 에이전트 스택입니다.