pi-rust

pi-rust documentation

How to install pi-rust, run pi, connect models, editors, and MCP servers, and write extensions. The docs match the latest pi-rust release.

Get started

  • Quick start

    The commands to start pi in a project, run one prompt, resume a session, and pick a model.

  • Install pi-rust

    It downloads the latest release for your platform. It compares the archive with SHA256SUMS. It installs pi in ~/.local/bin.

  • Configuration files

    pi-rust uses your existing pi folder: logins, settings, models, key bindings, MCP servers, extensions, skills, and sessions.

  • Differences from upstream pi

    What pi-rust adds to the TypeScript pi, where its runtime behaves differently, and which upstream bugs it already fixes.

Use pi

  • Interactive commands

    In interactive mode, type / to see the list of commands. Examples are /login, /model, /settings, /tree, /fork, /compact, /export, /share, /mcp, and /hotkeys.

  • CLI commands and flags

    Run pi --help to see all options. This page explains session working directories and the commands that pi-rust adds: pi completion, pi doctor, pi sessions, pi…

  • Settings

    Settings load from <agent dir>/settings.json (normally ~/.pi/agent/settings.json). A trusted project's .pi/settings.json overrides global values.

  • Terminal

    To select a harness theme, open /settings and select Theme. In interactive mode, when a run takes 10 seconds or more, pi sends a terminal notification at the…

  • Status line

    The custom status line is the marketplace:statusline extension. Earlier pi-rust versions had it built in. You can also install it from /extensions.

  • Deferred context

    Created: 2026-11-04. Last updated: 2026-11-04. pi-rust can keep skills and extension context entries, such as subagent configs, out of the system prompt.

Models and logins

  • Providers

    anthropic-messages openai-responses openai-completions openai-codex-responses (SSE and WebSocket) azure-openai-responses google-generative-ai google-vertex…

  • Subscription usage limits

    Created: 2026-10-30. Last updated: 2026-10-31. /usage, pi usage, and the native extension method usage.get show the limits of pi's subscription logins.

Editors and tools

  • MCP servers

    By default pi connects every enabled MCP server of mcp.json in the background when a session starts.

  • ACP mode for Zed and other editors

    pi --mode acp runs pi as an Agent Client Protocol (ACP) server over stdio. Editors such as Zed can then use pi as an external agent.

  • ACP agents as providers

    Created: 2026-10-30. Last updated: 2026-11-04. pi can run an external Agent Client Protocol (ACP) agent, such as Kiro CLI or Amp, and show its work in the pi…

  • RPC mode

    pi --mode rpc reads JSON commands on stdin and writes responses and session events on stdout, one JSON record per line, as upstream pi does.

Extensions

  • Extension marketplace

    The marketplace contains native Rust extensions for pi-rust. Each release has a signed index and binary archives for supported platforms.

  • Native extension protocol

    Created 2026-10-29. Last updated 2026-11-02. A native extension is a program that pi starts as a child process. pi and the child exchange JSON-RPC 2.0 messages.

Reference

  • Crates

    The Rust crates in the pi-rust workspace: pi-ai, pi-agent, pi-tui, pi-mcp, pi-js, pi-coding-agent, and the rest.

Try