2026-07-07 01:54 UTCIn-site rewrite5 min readUpdated: 2026-07-07 02:51 UTC

Pi (Rust): High-performance AI coding agent CLI written in Rust

pi_agent_rust is a from-scratch Rust port of Pi Agent, offering instant startup, stable streaming, 8 built-in tools, and an extension system with capability-based security, addressing performance issues of existing AI coding assistants.

SourceHacker News AIAuthor: rsyring

Notifications You must be signed in to change notification settings

Fork 149

Star 1.3k

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

3,569 Commits

.beads

.cargo

.claude/skills/pi-agent-rust

.github

benches

docs

examples

fuzz

legacy_pi_mono_code/pi-mono

proptest-regressions

scripts

src

tests

themes

.gitattributes

.gitignore

.no-mock-allowlist

.rchignore

.ubsignore

AGENTS.md

CHANGELOG.md

Cargo.lock

Cargo.toml

LICENSE

README.md

build.rs

gh_og_share_image.png

install.sh

pi_agent_rust_illustration.webp

rust-toolchain.toml

uninstall.sh

verify

Repository files navigation

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?" 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:

Extension assurance signal Why you should care

Two-stage exec guard (exec capability policy + command-level mediation + DCG/heredoc AST signals) Dangerous shell intent is caught before spawn, including destructive payloads hidden in multiline wrappers

Trust lifecycle + kill switch (pending/acknowledged/trusted/killed) You can quarantine an extension instantly, log who pulled the switch and why, and require explicit re-acknowledgement before restoring access

Hostcall lane kill-switch controls (forced_compat_global_kill_switch, forced_compat_extension_kill_switch) Fast-path regressions can be contained immediately by forcing compatibility-lane execution without disabling the extension system

Deterministic hostcall reactor mesh (shard affinity, bounded SPSC lanes, backpressure telemetry, optional NUMA slab tracking) Runtime behavior stays predictable under contention; queue pressure and routing decisions are observable instead of opaque

Startup prewarm + warm isolate reuse for JS runtimes Runtime creation overlaps startup and warm reuse keeps repeated extension runs low-latency without a Node/Bun process model

Tamper-evident runtime risk ledger (verify / replay / calibrate) Security decisions are hash-linked and can be replayed or threshold-tuned from real runtime traces

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.

Technique What we do Runtime effect

Cold-start minimization Single static binary, no Node/Bun runtime bootstrap, no JIT warmup, startup prewarm for extension runtime paths Faster time-to-first-interaction

Less copying on hot paths Arc/Cow message flow, zero-copy hostcall/tool payload handling, reduced clone-heavy provider/session paths Lower CPU and allocation pressure

Deterministic dispatch core Typed hostcall opcodes, fast-lane/compat-lane routing, bounded shard queues with reactor-mesh telemetry Better tail latency under concurrent extension load

Efficient long-session storage SQLite session index + v2 sidecar (segmented log + offset index) with O(index+tail) reopen path Fast resume on large histories

Streaming parser tuned for real networks SSE parser tracks scanned bytes, handles UTF-8 tails, normalizes chunk boundaries, interns event-type strings Lower streaming overhead and fewer parser stalls

Safe fast-path controls Shadow dual execution sampling, automatic backoff on divergence/overhead, compatibility-lane kill switches for containment Keeps optimizations fast without silent behavior drift

CI-level performance governance Scenario matrices, strict artifact contracts, fail-closed perf gates Regressions are caught before release

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?

Feature Pi (Rust) Typical TS/Python CLI

Startup [args].

Packages: Share bundles with pi install npm:@org/pi-packages (skills, prompts, themes, extensions).

Autocomplete

Pi provides context-aware autocomplete in the interactive editor:

@ file references: Type @ followed by a path fragment to attach file contents. The completion engine indexes project files (respecting .gitignore) via the ignore crate's WalkBuilder, capping at 5,000 entries.

/ slash commands: Built-in commands (/help, /model, /tree, /clear, /compact, /exit) and user-defined prompt templates and skills all appear as completions.

Fuzzy scoring: Prefix matches rank above substring matches. Results are sorted by match quality, then by kind (commands > templates > skills > files > paths).

Background refresh: A background thread re-indexes the project file tree every 30 seconds, so completions stay current without blocking the input loop.

Three Execution Modes

Pi runs in three modes, each suited to different workflows:

Mode Invocation Use Case

Interactive pi (default) Full TUI with streaming, tools, session branching, autocomplete

Print pi -p "..." Single response to stdout, no TUI, scriptable

RPC pi --mode rpc Headless JSON protocol over stdin/stdout for IDE integrations

Interactive mode provides the full experience: a multi-line text editor with history, scrollable conversation viewport, model selector (Ctrl+L), scoped model cycling (Ctrl+P/Ctrl+Shift+P), session branch navigator (/tree), and real-time token/cost tracking.

Print mode sends one message, streams the response to stdout, and exits. Useful for shell scripts and one-off queries.

RPC mode exposes a line-delimited JSON protocol for programmatic control. Clients send commands (prompt, steer, follow-up, abort, get-state, compact) and receive streaming events. This is how IDE extensions and custom frontends integrate with Pi. See RPC Protocol for the wire format.

Extensions

Pi supports two extension runtime families with capability-gated host connectors:

JS/TS entrypoints run without Node or Bun in an embedded QuickJS runtime.

*.native.json descriptors run in the native-rust descriptor runtime.

Extension entrypoints are auto-detected:

.js/.ts/.mjs/.cjs/.tsx/.mts/.cts run directly in embedded QuickJS (no descriptor conversion).

*.native.json loads the native-rust descriptor runtime.

One session currently uses one runtime family at a time (JS/TS or native descriptor).

Sub-100ms cold load (P95), sub-1ms warm load (P99)

Node API shims for fs, path, os, crypto, child_process, url, and more

Capability-based security: extensions call explicit connectors (tool/exec/http/session/ui) with audit logging

Command-level exec med

[truncated for AI cost control]