pi-rust

pi-rust is a Rust port of the pi coding agent harness. It has these parts:

• A streaming API for large language models (LLMs) from many providers.
• An agent loop that calls tools.
• The pi coding agent, which has a command-line interface (CLI).

pi-rust does not need Node.js or a different JavaScript runtime. In this file, "upstream pi" is the original pi, which is written in TypeScript.

Install

Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/yannelli/pi-rust/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/yannelli/pi-rust/main/install.ps1 | iex

The script downloads the latest release, compares it with SHA256SUMS, and installs pi. For script options, manual install, and build from source, see Install.

Quick start

export ANTHROPIC_API_KEY=...        # or OPENAI_API_KEY, GEMINI_API_KEY, ...; or run /login
pi                                  # interactive session in the current directory
pi -p "Summarize src/main.rs"       # print mode: run once, print the answer
pi --mode json -p "List the TODOs"  # one JSON event per line
pi --mode rpc                       # JSON-RPC over stdio for other programs
pi -c                               # continue the latest session here
pi -r                               # pick a session to resume
pi --model openai/gpt-5.5 --thinking high
pi @notes.md @screenshot.png "What changed?"
cat error.log | pi -p "Explain this error"
pi install npm:<package>            # install a pi package (extensions, skills, themes)

Run pi --help to see all options. In interactive mode, type / to see the commands.

Documentation

Configuration

pi-rust reads the same files as upstream pi, so the two can use one setup. To use a different folder in place of ~/.pi/agent, set PI_CODING_AGENT_DIR.

When pi-rust starts for the first time, it moves files from older pi layouts, as upstream pi does. For example, it moves oauth.json into auth.json.

Differences from upstream pi

pi-rust ports the upstream pi CLI and its libraries. This section lists the differences and SDK limits.

Runtime

• New Kimi Code OAuth logins use the global .ai endpoints. To sign in to mainland China, set KIMI_CODE_OAUTH_HOST=https://auth.kimi.com. The login stores its OAuth and API endpoints for later refreshes; older logins without this metadata retain their mainland endpoints. Explicit KIMI_CODE_OAUTH_HOST and KIMI_CODE_BASE_URL values override saved endpoints. A custom model baseUrl in models.json stays in effect. Kimi and Moonshot tool requests infer omitted types from enums, constants, and unambiguous schema structure.

• Extensions run on an embedded QuickJS engine, so pi-rust does not need Node.js. All Node built-in modules load. These include:

  • zlib with gzip, brotli, and zstd.
  • async_hooks with AsyncLocalStorage, and v8 serialization.
  • The network modules net, tls, dgram, dns, http, https, and http2.
  • vm contexts with timeouts, worker_threads, and cluster. They can send socket and server handles over inter-process communication (IPC).
  • node:sqlite on the bundled SQLite, node:test with TAP and spec output, and repl over any streams.
  • In-process inspector sessions, and wasi with a WebAssembly global on the wasmi interpreter.

  The APIs that do not work throw ERR_PI_UNSUPPORTED. Examples are crypto.subtle other than digest, and rare crypto ciphers such as Camellia. crates/pi-js/src/unsupported.rs lists all of them. Native npm addons cannot load on QuickJS.

  To run extensions on Node 22 or later, set extensionRuntime to "node" or "auto", or use --extension-runtime or PI_EXTENSION_RUNTIME. On Node, native addons, child_process.fork, and V8-only modules work. If Node is missing, pi uses QuickJS. See Node backend.

• IPC handle retries use a pi-js-specific wrapper. Internal handle listeners receive an object with only close(), and cluster connections queued to a disconnected worker are not reclaimed. See Extension runtime.

• On non-Linux Unix, a concurrent child spawn can inherit an IPC socket before QuickJS marks it close-on-exec. Node closes inherited descriptors in its macOS posix_spawn path. See Platform.

• The extension SDK still has gaps in child sessions, resource loading, and model runtimes. A DefaultResourceLoader with extensions serves one child session for each reload(), and its factories run in the extension host of the caller. SettingsManager supports custom storage and queued writes, with limits on JSON values and live object references. See Extension module exports for the remaining differences.

• The providers that extensions get from @earendil-works/pi-ai/providers/all stream, classify, generate images, and resolve auth in Rust. Their API key login asks for one key, also for Amazon Bedrock, Google Vertex AI, and Cloudflare. See Extension module exports.

• When you quit the interactive mode, pi waits at most 3 seconds for the running turn and the session_shutdown handlers, then exits. Upstream pi waits until they finish.

• grep and find use the Rust ignore crate, so pi-rust does not download rg or fd.

• The version check and pi update --self use the releases of this repository.

• Word movement in Chinese, Japanese, Korean (CJK), and Thai text uses ICU4X dictionaries. Thus some word boundaries are different from Intl.Segmenter in Node.

• pi-env looks for remote daemons in a pi-env-daemons folder next to the pi program. Each release has a pi-env-daemons-<tag>.tar.gz archive with the daemons for Linux, Android (Termux), macOS, and Windows on x86-64 and arm64. Extract this archive in the folder that contains pi.

• pi experimental and its commands server, client, durable, and vacation need PI_EXPERIMENTAL=1, as in upstream pi. server and client use Unix sockets. On Windows, they show a message that they need Unix. Upstream pi also has no Windows transport.

• When a local shell command exits, pi-durable still stops waiting for output 100 ms after the exit or the last chunk after it, as upstream does. It then delivers queued chunks and any chunk the readers finish reading before they observe the stop signal. On Unix it also takes at most 64 KiB more per stream if readable without waiting. On Windows it starts no further read. See Platform.

• Extension and login select menus show at most 10 options and fewer in short terminals, with a (n/total) counter, so the selected option stays visible. Upstream pi shows all options.

Additions

Bug fixes that are open upstream

The numbers are upstream issue numbers.

• If you remove a tool from the first tool list, later Anthropic requests do not fail (upstream issue 11376).
• On Bedrock, strict: "prefer" tools change to non-strict when the strict tools have more than 16 optional parameters (11416).
• modelOverrides in models.json also apply to classifier and image models: name, input, inputLimits, and cost. For classifiers, contextWindow and compat also apply (11223).
• The editor removes escape sequences from pasted text. If the end marker of a paste does not arrive, the paste ends after 10 seconds without input or at 16 MiB. Then Ctrl+C works again (11383).
• MCP HTTP replies that are plain JSON obey maxMessageBytes (11335).
• A code mode script can declare its own top-level tools or console (11226).
• Branch summaries from /tree use the selected thinking level (11444). If you resume a session after /tree, pi restores the thinking level that you used last (11451).
• pi removes mouse reports and other escape sequences with private parameters, such as ESC[<35;59;1M, from tool output (11377).
• In pi -p, a prompt that an extension command sends with sendUserMessage runs before pi exits (11238).
• An unpinned -e npm: package updates when npm has a newer version (11375).
• pi.exec keeps a maximum of 16 MiB of output from a command. It stops the command when the output gets to that limit (11360).
• pi-env watches a directory again after the kernel drops the watch and the directory keeps its inode (11342).

Crates

Development

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

The tests use the faux provider and local mock HTTP servers. They do not need API keys or network access.

Releases

Versions obey Semantic Versioning. The commit messages set the next version, as in Conventional Commits:

After continuous integration (CI) passes on main, the Release workflow runs cargo xtask plan. If a release is necessary, the workflow does these steps:

1. It increases the workspace version.
2. It adds the new section at the top of CHANGELOG.md.
3. It commits chore(release): vX.Y.Z and adds the tag vX.Y.Z.
4. It builds all targets.
5. It publishes the GitHub release with checksums.

Other ways to start the workflow:

• Push a vX.Y.Z tag that matches Cargo.toml. The workflow releases that version.
• Push a vX.Y.Z-rc.1 tag. The workflow publishes a pre-release.
• Run the workflow manually with dry_run. The workflow builds all targets and does not release.
• Run the workflow manually with bump set to patch, minor, or major, and with dry_run off. The workflow releases when the commits do not need a release.

cargo xtask plan                 # next version and release decision
cargo xtask prepare 0.2.0        # set the version and update CHANGELOG.md
cargo xtask notes 0.2.0          # print release notes

License

MIT. pi-rust is based on pi by Mario Zechner. See LICENSE.

These parts come from other projects. Each release archive includes their license notices.

The release archives also include THIRD-PARTY-LICENSES.md with the licenses of the third-party Rust crates in the binaries. The Release workflow writes it with cargo-about from about.toml and about.hbs.