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](https://github.com/badlogic/pi) by [Mario Zechner](https://github.com/badlogic) (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](https://github.com/Dicklesworthstone/asupersync)**: A structured concurrency async runtime with built-in HTTP, TLS, and SQLite - **[rich_rust](https://github.com/Dicklesworthstone/rich_rust)**: A Rust port of [Rich](https://github.com/Textualize/rich) by [Will McGugan](https://github.com/willmcgugan), 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: | 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](#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** | <100ms | 500ms-2s | | **Binary size** | ~21.1 MiB (default release) | 100MB+ (with runtime) | | **Memory (idle)** | <50MB | 200MB+ | | **Streaming** | Native SSE parser | Library-dependent | | **Tool execution** | Process tree management | Basic subprocess | | **Sessions** | JSONL with branching | Varies | | **Unsafe code** | Forbidden | N/A | ## 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](https://github.com/Dicklesworthstone/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](https://github.com/Dicklesworthstone/rich_rust) is a Rust port of Will McGugan's [Rich](https://github.com/Textualize/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?" ### Using a local model `ollama`, `llamacpp` (llama.cpp's `llama-server`), `mistralrs` (mistral.rs), and `lmstudio` are built-in **local** providers. The first three need **no API key** and work out of the box against their default ports: pi --provider ollama --model llama3 -p "hi" pi --provider llamacpp --model -p "hi" pi --provider mistralrs --model default -p "hi" To point at any other OpenAI-compatible server (a custom host/port, vLLM, etc.), add it to `~/.pi/agent/models.json`: { "providers": { "ollama": { "api": "openai-completions", "baseUrl": "http://127.0.0.1:11000/v1", "apiKey": "ollama", "models": [{ "id": "Qwen3.6-35B-A3B-4bit", "contextWindow": 32768 }] } } } Then `pi --provider ollama --model Qwen3.6-35B-A3B-4bit`. See [docs/models.md](docs/models.md) for the full `models.json` schema, provider aliases, and secret resolution (env vars and `!command` shell lookups). ## 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 | Tool | Description | Example | |------|-------------|---------| | `read` | Read file contents, supports images | Read src/main.rs | | `write` | Create or overwrite files | Write a new config file | | `edit` | Surgical string replacement | Fix the typo on line 42 | | `hashline_edit` | Precise edits using LINE#HASH tags | Apply edits to specific lines using hashline anchors | | `bash` | Execute shell commands with timeout | Run the test suite | | `grep` | Search file contents with context | Find all TODO comments | | `find` | Discover files by pattern | Find all *.rs files | | `ls` | List directory contents | What's in src/? | All tools include: - Automatic truncation for large outputs (2000 lines / 1MB) - Detailed metadata in responses - Process tree cleanup for bash (no orphaned processes) ### Session Management Sessions persist as JSONL files with full conversation history: # Continue most recent session pi --continue # Open specific session pi --session ~/.pi/agent/sessions/--home-user-project--/2024-01-15T10-30-00.jsonl # Ephemeral (no persistence) pi --no-session Sessions support: - Tree structure for conversation branching - Model/thinking level change tracking - Automatic compaction for long conversations ### Extended Thinking Enable deep reasoning for complex problems: pi --thinking high "Design a distributed rate limiter" Thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` ### Customization (Skills & Prompt Templates) - **Skills**: Drop `SKILL.md` under `~/.pi/agent/skills/` or `.pi/skills/` and invoke with `/skill:name`. - **Prompt templates**: Markdown files under `~/.pi/agent/prompts/` or `.pi/prompts/`; invoke via `/