rpi — a Rust-native coding-agent runtime

rpi is a library-first coding-agent runtime written in Rust, plus a terminal agent built on top of it. Ten composable crates span provider adapters, a durable crash-resumable agent loop, a reusable runtime, a terminal UI, and a stable plugin ABI — so the same code works as an embedded SDK or as a ready-to-run rpi command.

rpi began as a Rust reimplementation of the Pi TypeScript SDK by Mario Zechner. It now includes its own Rust-native plugin ABI and execution infrastructure. See Acknowledgements and NOTICE for upstream attribution.

Website: https://rpi.bigfisharc.cn/ · Docs: https://rpi.bigfisharc.cn/docs.html

Interactive TUI. See docs/guides/user-guide.md for the full command surface.

The agent loop and a real write tool round-trip, recorded with no API key and no network — the same path the tests take. Source of truth is demo/sdk.tape; regenerate with task demo.

Three ways to use it

The three share one implementation. Build your tools once, debug them inside an embedded agent, and ship the same code as a cdylib plugin that the global rpi loads. See docs/agent/project-structure.md for the recommended project layout.

Install

Prebuilt binary (no Rust toolchain needed):

curl -fsSL https://raw.githubusercontent.com/bigfish1913/pi-rust/main/scripts/install.sh | sh

Verifies the published SHA-256 checksum and installs to /usr/local/bin or ~/.local/bin. Preview first with --dry-run.

On Windows (x64), run in PowerShell 5.1 or later:

& ([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/bigfish1913/pi-rust/main/scripts/install.ps1).Content))

Verifies the published SHA-256 checksum and installs to $env:LOCALAPPDATA\Programs\rpi. Follow the printed instructions to add it to PATH, then run rpi --version. Append -DryRun to preview, or use -Version 0.3.22 and -Dir 'C:\Tools\rpi' to select a version and directory.

From crates.io (requires Rust 1.78+):

cargo install rpi-cli
rpi --version

Package managers:

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

The Homebrew formula currently supports Apple silicon on macOS. Intel Macs can use the prebuilt installer for releases with an x86_64-apple-darwin asset, or cargo install rpi-cli. A winget manifest is open for review.

From source:

git clone https://github.com/bigfish1913/pi-rust.git
cd pi-rust && cargo run -p minimal   # offline agent, no API key required

Real output of the two offline examples — no credentials, no network, identical bytes every run. Regenerate with task demo-transcript:

$ cargo run -q -p minimal
minimal example: 2 messages after run
  - user
  - assistant
assistant reply: Hello from the faux provider!
AgentEnd observed.

$ cargo run -q -p tools-example
tools example: 4 messages after run
wrote out.txt (28 bytes): "hello from the tools example"
AgentEnd observed; tool ran against OsExecutionEnv.

Quick start

The CLI

export ANTHROPIC_API_KEY=...          # or OPENAI_API_KEY, or ~/.rpi/agent/models.json
rpi                                   # interactive TUI
rpi -p "summarize the README"         # one-shot
rpi --mode json -p "list the crates"  # machine-readable event stream

Sessions persist as JSONL and survive a crash mid-run; rpi resumes from the last committed frame rather than replaying the turn. Custom Anthropic or OpenAI-compatible gateways are declared in ~/.rpi/agent/models.json and selected with --model <provider>/<model>.

Request timeouts and model compatibility

--timeout 600 limits a whole LLM request, including its streamed response. --stream-idle-timeout 300 independently limits silence between response body bytes after the response starts. Every non-empty chunk resets the idle timer, including SSE keepalives and partial frames. A stalled stream produces a retryable error; the configured retry policy controls whether it is retried. Healthy streams may run longer than the idle timeout, up to the total deadline. Use --stream-idle-timeout 0 to disable the idle timer. You can also set "streamIdleTimeout": 300 (seconds) in ~/.rpi/agent/settings.json; the CLI flag takes precedence. httpIdleTimeout only expires unused pooled connections and does not control an active response.

For providers with "api": "openai-completions", put compatibility flags in each model's compat object in ~/.rpi/agent/models.json, for example:

"compat": {
  "thinkingFormat": "deepseek",
  "requiresReasoningContent": true
}

requiresReasoningContent replays assistant thinking in reasoning_content, including an empty string for assistant messages without thinking. The pi name requiresReasoningContentOnAssistantMessages is accepted as an alias; if both are present, the rpi spelling wins and conflicting values produce a warning. thinkingFormat supports "openai" (the default request shape) and "deepseek" (also sends thinking: { "type": "enabled" | "disabled" } for reasoning-capable models). supportsReasoningEffort: false suppresses reasoning_effort if the gateway does not accept it. requiresThinkingAsText instead places thinking in ordinary text content. Unknown compat fields and invalid values produce warnings naming the provider and model; invalid compat objects are ignored. Other pi thinking formats are not currently supported.

The SDK

Build an agent against a deterministic in-process provider — no API key, no network, no flakiness:

use rpi_agent::AgentBuilder;
use rpi_ai::providers::faux::{FauxProvider, FauxScript};
use rpi_ai::Provider;

#[tokio::main]
async fn main() {
    // `FauxProvider::new` already returns an `Arc<Self>`.
    let provider = FauxProvider::new(FauxScript::new().with_text("Hello from the faux provider!"));
    let model = provider.default_model().clone();

    let agent = AgentBuilder::new()
        .model(model)
        .system_prompt("You are a helpful assistant.")
        .stream_fn(make_stream_fn(provider))
        .build()
        .expect("agent builds");

    let mut events = agent.subscribe();
    agent.prompt("hi").await.expect("prompt completes");

    while let Ok(ev) = events.try_recv() {
        let _ = ev; // AgentEvent::{MessageUpdate, ToolEnd, AgentEnd, …}
    }
    println!("{} messages after the run", agent.state().messages.len());
}

make_stream_fn bridges the synchronous StreamFn contract to the async provider — the full version is in examples/minimal/src/main.rs (cargo run -p minimal).

Crates

Ten workspace crates, one shared version. Dependency direction is one-way and enforced in review:

rpi-telemetry → rpi-ai → rpi-agent → rpi-tools → rpi-harness
                    ↘ rpi-runtime

Five crates sit outside that chain:

• rpi-tui depends on no other rpi-* crate.
• rpi-runtime depends on rpi-ai and provides embeddable model catalogs, credential resolution and execution bindings. See the runtime guide.
• rpi-plugin-sdk is a leaf too (it has no rpi-* deps), but it is not only the host's plugin contract: rpi-tools also reads its env-var names, so the host and its plugins cannot disagree about the strings they exchange across the ABI. That edge is names-only — nothing is linked or called.
• rpi-extensions is rpi-plugin-sdk plus rpi-ai/rpi-agent, since it hosts plugins that run tools.
• rpi-cli depends on all ten of the others, which is how the rpi binary gets the TUI, the harness and the plugin loader at once.