An independent Rust implementation of the Pi agent. This project uses Pi as its compatibility baseline and aims to keep the coding-agent harness aligned with Pi's features, wire formats, runtime behavior, and user-facing semantics while implementing them in Rust.

This is a learning project, not an official Pi distribution or a loose Pi-inspired rewrite. Compatibility with the upstream Pi agent is the goal. The current P0 milestone focuses on the headless harness boundary and does not yet include Pi's TUI.

pi-rust tracks Pi Agent as the reference implementation. Where a feature exists in the current milestone, the intended behavior is Pi-compatible rather than a project-specific approximation. In particular, prompt construction, tools, project trust, the agent loop, context management, model metadata, provider routing, RPC events, and session persistence are designed to produce the same experience at the headless evaluation boundary.

The project is being aligned incrementally:

Compatibility gaps are treated as work to be completed, not intentional product differences, unless this README explicitly says otherwise.

• Pi-compatible LF-delimited RPC JSONL for evaluator and client integration
• Pi v3 sessions, including resume, tree, fork, clone, compaction, and preservation of unknown entries
• Prompt, steering and follow-up queues, abort, retry, thinking levels, and long-context recovery
• Model metadata generated from Pi's catalog and checked into the binary at build time
• Anthropic Messages, OpenAI Responses and Chat Completions, Google Generative AI, AWS Bedrock, OpenAI Codex, Azure Responses, and Radius pi-messages protocol families
• read, bash, edit, and write coding tools, with optional grep, find, and ls
• Isolated user state by default, plus explicit interoperability with an existing Pi agent directory

P0 intentionally excludes the TUI, image execution, interactive OAuth login/refresh, Vertex ADC, skills, extensions, packages, prompt templates, and themes. Unsupported RPC operations return explicit errors instead of silently succeeding.

Download an archive for your platform from GitHub Releases, unpack it, and put pi-rust (or pi-rust.exe) on your PATH.

Release tags publish these native binaries:

Each release includes SHA256SUMS. To build locally, install Rust 1.94.1 or newer and run:

git clone https://github.com/YingchaoX/pi-rust.git
cd pi-rust
cargo build --release --locked
./target/release/pi-rust --help

Set the API key for a supported provider and give the harness a prompt:

export ANTHROPIC_API_KEY=...
pi-rust --provider anthropic --ephemeral "Inspect this repository"

export OPENAI_API_KEY=...
pi-rust --provider openai --ephemeral "Fix the failing tests"

export DEEPSEEK_API_KEY=...
pi-rust --provider deepseek --ephemeral "Explain this codebase"

Provider detection uses available credentials when --provider is omitted. Run pi-rust --list-providers to see the complete catalog, default models, credential environment variables, and selected protocols. Select a model with --model PROVIDER_MODEL_ID and override a compatible endpoint with --base-url URL.

The default tools are read,bash,edit,write. Passing --tools creates an allow-list; optional tools must be enabled explicitly:

pi-rust --provider deepseek \
  --tools read,bash,grep,find,ls \
  --no-tools write,edit \
  "Audit this repository without changing files"

RPC mode is the stable headless boundary for harness evaluation. It reserves stdout for one JSON object per line; logs and diagnostics go to stderr.

printf '%s\n' '{"id":"1","type":"get_state"}' \
  | pi-rust --mode rpc --provider deepseek --ephemeral --approve

The runtime supports prompt/queue/abort/state, model and thinking changes, manual compaction and retry, bash execution, and P0 session operations. Prompt acceptance is asynchronous: clients should continue consuming agent events until agent_settled. Non-empty image input and export_html currently return Pi-shaped unsupported errors.

--approve and --no-approve only record whether project-local configuration and context files are trusted. They are not per-tool authorization controls.

State is isolated under ~/.pi-rust/agent by default. Point at another directory only when interoperability is intentional:

pi-rust --agent-dir ~/.pi/agent --provider deepseek "Resume compatible Pi data"
# Equivalent environment variable:
export PI_CODING_AGENT_DIR="$HOME/.pi/agent"

Sessions are grouped by working directory under sessions/. New sessions use Pi v3 headers, UUIDv7 IDs, ISO timestamps, and camelCase wire fields. Headerless legacy pi-rust sessions remain readable but are never rewritten in place.

Settings are recursively merged with this precedence:

1. CLI arguments
2. trusted project .pi/settings.json
3. agent-directory settings.json
4. built-in defaults

P0 settings cover default provider/model/thinking, transport, queue modes, compaction, retry, thinking budgets, session directory, and HTTP/WebSocket timeouts.

The checked-in catalog currently mirrors Pi's text-provider catalog and routes each model using its metadata rather than provider-wide protocol assumptions. API-key providers read the environment variables printed by --list-providers.

OpenAI Codex can reuse an existing Pi auth.json. Bedrock uses the AWS SDK default credential chain and supports AWS_BEARER_TOKEN_BEDROCK. OAuth-only providers require an existing Pi credential or explicit token because interactive login and token refresh are not part of P0.

To refresh the model snapshot from an explicit Pi checkout:

cargo run --bin sync-models -- --pi-dir ../pi

The command validates provider/model uniqueness and records upstream provenance in data/models.meta.json; normal execution never depends on ../pi.

Like upstream Pi, pi-rust has no built-in sandbox or per-tool permission dialog. Tool calls inherit the filesystem, process, and network permissions of pi-rust. Use a disposable checkout, container, VM, or another OS-level sandbox for unattended evaluation, and avoid exposing credentials that the evaluated task does not require.

The same commands run in CI:

cargo fmt --all -- --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --all-targets --locked

CI runs formatting and Clippy on Linux, then runs all tests on Linux, Windows, and macOS. Dependabot checks Cargo and GitHub Actions dependencies weekly.

To publish a release, first update the version in Cargo.toml, commit the matching Cargo.lock, then push a semantic version tag:

git tag v0.1.0
git push origin v0.1.0

The release workflow builds four native archives, generates SHA-256 checksums, and creates the GitHub Release with generated notes. See the project research notes for the original scope analysis.

MIT. See LICENSE and NOTICE.