pi_agent_rust

pi_agent_rust - Native 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: Managed runtimes can add noticeable startup overhead - Resource intensive: Electron apps or heavy runtimes can add substantial overhead - 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!). Official release archives install the single end-user binary pi, with streaming responses and 36 built-in tools (19 in the default --tools list; 14 always in the model's schema, the rest reachable through the xdev dispatcher or enabled in settings).

Current product direction

This project is no longer trying to be a strict drop-in replacement for the legacy TypeScript Pi. That target became both impractical and undesirable as the legacy implementation evolved. Legacy Pi remains useful historical context, but it is not our compatibility authority or definition of completeness.

OMP is the closer reference for where the product is going: feature surface, agent workflows, look and feel, and overall UI/UX. Pi Rust still chooses Rust-native architecture and may intentionally differ from both projects when that produces a simpler, safer, or better coding agent. Historical drop-in and parity artifacts remain in the repository as records; they do not gate product work, releases, or user-facing claims.

All repository quality checks, builds, and releases run through Doodlestein Self-Releaser (DSR). Contributors must not invoke Cargo or RCH directly, and GitHub Actions is never an execution or evidence authority for this project. Use dsr quality --tool pi_agent_rust for the registered quality recipe and the canonical DSR build/release commands documented in docs/releasing.md.

For signed published payload verification and offline CLI smoke checks, see Published release consumer checks.

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:

• A native single-binary design intended to minimize startup and runtime overhead
• A bounded-resource architecture for long-running sessions
• A capability-gated 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 show data and a passing result for every declared budget, with no 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

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

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

Two additional machine-recognized citation forms exist:

• *(from [artifact-path])* — path-only citation. The cited artifact must exist and parse; freshness is enforced by the same 14-day rule as release-facing claims.
• *(from [artifact-path]; historical snapshot)* — explicit historical contract. The citation itself declares the obligation a retained snapshot: existence and validity are still checked, but staleness is not enforced because such claims never satisfy current release-facing requirements.

scripts/check_readme_evidence_freshness.py (a pre-release check listed in docs/releasing.md, not part of the code quality recipe) checks file freshness and artifact content so stale, no-data, or correlation-mismatched evidence cannot back user-facing performance claims; for release-facing citations of budget_summary.json it validates the full pi.perf.budget_summary.v2 contract, including that the header counts equal the per-budget rows. It reports line-numbered proof obligations for cited claims and extracts claim-gated performance phrases for reviewer audit. Historical snapshot citations are mapped separately and do not satisfy current release-facing claims.

Performance-Oriented Architecture

In this README, we means the project owner and collaborating coding agents.
The design concentrates performance work in several runtime layers rather than assuming one optimization proves an end-to-end result.