pi_agent_rust

pi_agent_rust - High-performance AI coding agent CLI written in Rust

Why Should You Care? • TL;DR • Methodology • Quick Start • Features • Installation • Commands • Configuration

# Install latest release
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)" | bash

The Problem

You want an AI coding assistant in your terminal, but existing tools are: - Slow to start: Node.js/Python runtimes add 500ms+ before you can type - Memory hungry: Electron apps or heavy runtimes eat gigabytes - Unreliable: Streaming breaks, sessions corrupt, tools fail silently - Hard to extend: Closed ecosystems or complex plugin systems

The Solution

pi_agent_rust is a from-scratch Rust port of Pi Agent by Mario Zechner (made with his blessing!). Single binary, instant startup, stable streaming, and 8 built-in tools.

Rather than a direct line-by-line translation, this port builds on two purpose-built Rust libraries: - asupersync: A structured concurrency async runtime with built-in HTTP, TLS, and SQLite - rich_rust: A Rust port of Rich by Will McGugan, providing beautiful terminal output with markup syntax

# Start a session
pi "Help me refactor this function to use async/await"

# Continue a previous session
pi --continue

# Single-shot mode (no session)
pi -p "What does this error mean?" < error.log

Why Should You Care?

If you already use Pi Agent, especially through OpenClaw, this project keeps the core workflow while upgrading the engine under the hood:

• Substantially faster in realistic end-to-end flows (not synthetic microbenchmarks)
• Dramatically smaller memory footprint in long-running sessions
• Materially stronger security model for extension/tool execution, including command-level blocking of dangerous extension shell patterns

Security is a first-class design goal here, not a bolt-on:

• Capability-gated hostcalls (tool/exec/http/session/ui/events)
• Two-stage extension exec enforcement: capability gate first, then command mediation that blocks critical shell classes by default (for example recursive delete, disk/device writes, reverse shell) and can tighten to block high-tier classes in strict/safe policy
• Policy + runtime risk + quota enforcement on the execution path
• Per-extension trust lifecycle (pending -> acknowledged -> trusted -> killed) with kill-switch audit logs and explicit operator provenance
• Hostcall-lane emergency controls that can force compatibility-lane execution globally or for one extension when fast-lane behavior needs immediate containment
• Structured concurrency via asupersync for more predictable cancellation/lifecycle behavior
• Auditable runtime signals/ledgers and redacted security alerts for extension behavior

TL;DR (Pi/OpenClaw Users)

The Rust port is designed around large-session, multi-agent, and extension-heavy workloads. Release-facing performance numbers are published only when the checked-in evidence artifacts are current, have matching run provenance, and report no CI no-data or data-contract failures. Historical benchmark snapshots are retained in planning/evidence artifacts, but they are not treated as current README claims until the performance evidence gate is regenerated cleanly.

Extension runtime guarantees are also concrete:

Bottom line: Pi's architecture targets lower latency, lower memory use, and stronger extension runtime safety under real workload pressure; current numeric claims must come from fresh, provenance-matched evidence artifacts.

_{Data source: docs/planning/BENCHMARK_COMPARISON_BETWEEN_RUST_VERSION_AND_ORIGINAL__GPT.md (latest secure-path + full orchestrator checkpoints, 2026-04-23).}

README Citation Convention

All numeric performance claims in this README include inline citations with format: *(from [artifact-path], run [correlation-id])*

Example: *(from [artifact-path], run [correlation-id])*

CI checks both file freshness and artifact content so stale, no-data, or correlation-mismatched evidence cannot back user-facing performance claims. The README evidence checker reports line-numbered proof obligations for cited claims and extracts claim-gated performance phrases for reviewer audit. Explicit historical snapshot citations are mapped separately and do not satisfy current release-facing claims.

How We Made It So Fast

In this README, we means the project owner and collaborating coding agents.
The speed gains come from runtime design, not one trick.

If you want the full implementation inventory, see Performance Engineering.

Benchmark Methodology and Claim Integrity

The benchmark evidence policy is designed to keep results realistic, reproducible, and hard to game.

What we measured:

• Matched-state workloads: resume a large session and append the same 10 messages.
• Realistic E2E workloads: resume + append + extension activity + slash-style state changes + forks + exports + compactions.
• Scale levels: from 100k up to 5M token-class session states.
• Startup/readiness: command-level readiness (--help, --version) separately from long-session workflows.

How we kept comparisons fair:

• Two scopes in the benchmark report:
• apples-to-apples (pi_agent_rust vs legacy coding-agent)
• apples-to-oranges (legacy stack components included where legacy behavior is outsourced)
• Release-mode binaries and repeated runs per matrix cell.
• No paid-provider noise in core latency/footprint tables (provider-call costs are excluded from these core comparisons).

How we kept claims honest:

• Security controls stayed on during secure-path measurements (no policy/risk/quota bypasses for speed claims).
• Raw artifacts are preserved (JSON/trace/time outputs) and called out in the benchmark report.
• Blockers are explicitly disclosed: when direct legacy reruns were blocked by missing workspace deps, we state that and compare against prior validated legacy artifacts instead of pretending reruns succeeded.
• Interpretation notes are explicit: the report distinguishes baseline sections vs fresh reruns so readers can see exactly which values came from which run set.
• Reproducibility over marketing: methodology, caveats, and known limits are included alongside wins.

If you want full details, see:

• docs/planning/BENCHMARK_COMPARISON_BETWEEN_RUST_VERSION_AND_ORIGINAL__GPT.md (methodology + results + caveats + raw artifact paths)

Why Pi?

Quick Example

# 1) Start an interactive session
pi

# 2) Ask a codebase question
pi "Summarize the architecture in src/"

# 3) Attach a file inline
pi @src/main.rs "Explain startup flow"

# 4) Run single-shot mode for scripting
pi -p "List likely regression risks for this diff"

# 5) Continue your last project session
pi --continue

# 6) Inspect available models/providers
pi --list-models
pi --list-providers

Foundation Libraries

asupersync

asupersync is a structured concurrency async runtime designed for applications that need predictable resource cleanup. Key features used by pi_agent_rust:

• Capability-based context (Cx): Async functions receive an explicit context that controls what they can do (HTTP, filesystem, time). This makes testing deterministic.
• HTTP client with TLS: Built-in HTTP API with rustls, avoiding OpenSSL dependency hell
• Structured cancellation: When a parent task cancels, all child tasks cancel cleanly. No orphaned futures.

pi_agent_rust runs on asupersync end-to-end today (runtime + HTTP/TLS + cancellation). Provider streaming uses a minimal HTTP client (src/http/client.rs) feeding a custom SSE parser (src/sse.rs).

rich_rust

rich_rust is a Rust port of Will McGugan's Rich Python library. It provides:

• Markup syntax: [bold red]error[/] renders as bold red text
• Tables: ASCII/Unicode table rendering with alignment and borders
• Panels: Boxed content with titles
• Progress bars: Animated progress indicators
• Markdown: Terminal-rendered markdown with syntax highlighting
• Themes: Consistent color schemes across components

The terminal UI uses rich_rust for all output formatting, providing the same visual quality as Rich-based Python tools.

Quick Start

1. Install

# Install latest release binary
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)" | bash

If you already have the original TypeScript pi installed, the installer asks whether to make Rust Pi canonical as pi and automatically create legacy-pi for the old command.

2. Configure API Key

export ANTHROPIC_API_KEY="sk-ant-..."

3. Run

# Interactive mode
pi

# With an initial message
pi "Explain this codebase structure"

# Read files as context
pi @src/main.rs "What does this do?"

Features

Streaming Responses

Real-time token streaming with extended thinking support:

pi "Write a quicksort implementation"

Watch the response appear token-by-token, with thinking blocks shown inline.

8 Built-in Tools