pi-rust MCP server
Commit Nov 15, 2026A Rust-based coding agent harness that provides a streaming API for LLMs, an agent loop for tool calling, and a command-line interface.
Also known as yannelli/pi-rust
- Stars
- 13
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is pi-rust MCP?
pi-rust is a Rust-based coding agent harness that provides a streaming API for LLMs, an agent loop for tool calling, and a command-line interface.
Summary generated from the project's README
About pi-rust MCP server
Developers looking for a high-performance coding agent harness can use pi-rust to manage large language models through a streaming API and an automated agent loop for tool calling. This Rust-based implementation provides a command-line interface for interactive coding sessions, allowing users to run single commands in print mode or use JSON-RPC over stdio for integration with other programs. It functions locally on Linux, macOS, and Windows, requiring API keys for providers like Anthropic, OpenAI, or Gemini.
Unlike the original TypeScript version, this version does not require a Node.js runtime because it uses an embedded QuickJS engine to run extensions. It includes specialized tools such as slash commands for diffing, reviewing, and undoing actions, as well as a marketplace for installing native Rust extensions, skills, and themes. Users can manage complex workflows by resuming previous sessions, exporting conversations to Markdown, or utilizing the ACP mode for editors like Zed.
What you can do with it
- 1Summarizing source filesA developer can pass a specific file to the agent to get a quick summary via the print mode.
- 2Extending agent capabilitiesUsers can expand the functionality of the agent by installing new packages from a marketplace.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
ANTHROPIC_API_KEY
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableyannelli/pi-rust is public and reachablegithub.com/yannelli/pi-rust ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/yannelli/pi-rust ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubpi-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
picoding 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
Homebrew (macOS and Linux):
brew install yannelli/tap/pi
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
| Page | Contents |
|---|---|
| Install | Script options, manual install, provenance check, update, and build from source |
| Interactive commands | /diff, /context, /export, /init, /review, /undo, /retry, and prompt history |
| CLI commands and flags | pi completion, pi doctor, pi sessions, pi stats, run limits, structured output, and pi extensions |
| Extension marketplace | Find, install, update, and remove native Rust extensions |
| Providers | Wire protocols, logins, Cursor, Google Antigravity, disabledProviders, OpenRouter, and account model lists |
| Status line | The marketplace:statusline extension and the move from the built-in status line |
| Terminal | Themes, notifications, and the marketplace:iterm2 extension |
| ACP mode | pi --mode acp for Zed and other editors |
| ACP agents | Kiro CLI, Amp, and ACP registry agents as providers, /acp, and the acpAgents setting |
| Docs index | Agent playbooks, parity, and the protocol notes of the subscription providers |
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.
| Path | Contents |
|---|---|
~/.pi/agent/auth.json |
API keys and OAuth logins from /login or pi auth |
~/.pi/agent/settings.json |
Settings. In a trusted project, <project>/.pi/settings.json overrides them. |
~/.pi/agent/models.json |
Custom providers and models |
~/.pi/agent/keybindings.json |
Key bindings |
~/.pi/agent/mcp.json, <project>/.pi/mcp.json |
MCP servers |
~/.pi/agent/{extensions,skills,prompts,themes}/ |
Extensions, skills, prompt templates, and themes. .pi/ in a project and ~/.agents/skills also work. |
AGENTS.md, CLAUDE.md, SYSTEM.md, APPEND_SYSTEM.md |
Context files and system prompt overrides |
~/.pi/agent/sessions/ |
Sessions as JSONL trees in the pi format |
~/.pi/agent/prompt-history.jsonl |
The prompts that you sent, for Up, Down, and Ctrl+R (pi-rust only) |
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
.aiendpoints. To sign in to mainland China, setKIMI_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. ExplicitKIMI_CODE_OAUTH_HOSTandKIMI_CODE_BASE_URLvalues override saved endpoints. A custom modelbaseUrlinmodels.jsonstays 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:
zlibwith gzip, brotli, and zstd.async_hookswithAsyncLocalStorage, andv8serialization.- The network modules
net,tls,dgram,dns,http,https, andhttp2. vmcontexts with timeouts,worker_threads, andcluster. They can send socket and server handles over inter-process communication (IPC).node:sqliteon the bundled SQLite,node:testwith TAP and spec output, andreplover any streams.- In-process
inspectorsessions, andwasiwith aWebAssemblyglobal on the wasmi interpreter.
The APIs that do not work throw
ERR_PI_UNSUPPORTED. Examples arecrypto.subtleother thandigest, and rarecryptociphers such as Camellia.crates/pi-js/src/unsupported.rslists all of them. Native npm addons cannot load on QuickJS.To run extensions on Node 22 or later, set
extensionRuntimeto"node"or"auto", or use--extension-runtimeorPI_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_spawnpath. See Platform. -
The extension SDK still has gaps in child sessions, resource loading, and model runtimes. A
DefaultResourceLoaderwith extensions serves one child session for eachreload(), and its factories run in the extension host of the caller.SettingsManagersupports 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/allstream, 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_shutdownhandlers, then exits. Upstream pi waits until they finish. -
grepandfinduse the Rustignorecrate, so pi-rust does not downloadrgorfd. -
The version check and
pi update --selfuse 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.Segmenterin Node. -
pi-envlooks for remote daemons in api-env-daemonsfolder next to thepiprogram. Each release has api-env-daemons-<tag>.tar.gzarchive with the daemons for Linux, Android (Termux), macOS, and Windows on x86-64 and arm64. Extract this archive in the folder that containspi. -
pi experimentaland its commandsserver,client,durable, andvacationneedPI_EXPERIMENTAL=1, as in upstream pi.serverandclientuse 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.
-
Clearing the message queue (Esc while the agent works, the dequeue key, or the RPC
clear_queuecommand) removes only your queued messages. Queued extension messages, such as subagent or background task results, stay queued. When a run is aborted, queued extension messages join the conversation without starting a turn, so the agent sees them with your next prompt. A message an extension sends withtriggerTurnwhile the run is ending continues that run. Upstream pi drops queued extension messages with the queue, and in the second case leaves the message queued until the next prompt. -
In a linked git worktree, project files that the worktree lacks come from the main checkout:
.pi/settings.json,.pi/mcp.json,.pi/SYSTEM.md,.pi/APPEND_SYSTEM.md, and the.pi/skills,.pi/prompts,.pi/extensions, and.pi/themesfolders. The worktree's own copy wins. Project packages and relative entries resolve from the folder of the settings file that applies. A trust decision for the main checkout covers its worktrees unless the worktree folder has its own. Upstream pi reads only the worktree. See Settings. -
Extension and login
selectmenus 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
| Addition | Upstream pi | Docs |
|---|---|---|
The slash commands /diff, /init, /review, /context, /undo, and /retry |
Has none of them. Shows context use only in the footer. | Interactive commands |
Markdown export: /export notes.md and pi --export session.jsonl notes.md |
Exports only HTML and JSONL | Export |
Prompt history across sessions, with the Ctrl+R search and the promptHistory settings |
Keeps prompt history only while the process runs | Prompt history |
Alt+Down (Alt+S on Windows, app.message.sendNow) sends the queued follow-ups after the current turn. It moves them to the steering queue. |
Can only edit the queue or abort the turn | Interactive commands |
| Esc clears the input draft when the agent is idle, and undo restores the draft. Submitted slash commands join prompts and shell commands in the Up and Down history. | ||
pi completion and pi doctor |
Has neither command | CLI |
pi sessions and pi stats |
Lists and deletes sessions only in its session picker (pi -r and /resume). Shows usage only for the current session (/session). |
Sessions |
pi extensions lists, installs, removes, enables, and disables extensions through the package and resource settings |
Extensions | |
marketplace: package sources and pi extensions search and info use signed indexes and checksummed native binaries |
Has no Rust extension marketplace | Marketplace |
The /extensions browser searches, installs, updates, removes, enables, and disables extensions, then offers a reload |
Has no /extensions command |
/extensions |
Run limits (--max-turns, --max-cost) and structured output (--output-schema, --output-retries) |
Run limits | |
pi --mode acp. Permission modes are separate from thinking levels and control tool execution. The stdio MCP servers the client sends connect for that session. |
Needs the separate pi-acp adapter | ACP mode |
RPC and ACP modes run /usage, /context, /extensions [list|status|enable|disable], /fast, and /reload without a model call. RPC mode also runs /session, /changelog, /export, and /name, lists all of them in get_commands, sends their output as a command_output record, and sets agentInvoked in prompt responses. ACP mode sends config_option_update when the model, thinking level, or fast mode changes inside the session. |
Sends these prompts to the model in RPC mode | RPC mode |
| Account model lists for OpenAI Codex, Anthropic, GitHub Copilot, OpenAI, xAI, Google, and Cursor | Limits only OpenRouter | Account model lists |
Claude Mythos 5.2 (claude-mythos-5-2) is in the anthropic catalog with the settings and prices of Claude Fable 5.2. pi removes it for an account whose model list does not name it. |
Has no Mythos 5.2 model | Account model lists |
/usage, pi usage, and the native extension method usage.get show the subscription limits of the Claude, ChatGPT (Codex), Cursor, SuperGrok (xai, with Grok Build), and Google Antigravity logins: the 5-hour and weekly windows, the used percentage, and the reset time |
Has no usage report | Subscription usage limits |
Fast mode for models that have one: /fast, --fast, the fastMode setting, the ACP Fast mode option, and RPC set_fast_mode |
Has no fast mode | Fast mode |
The providers cursor and google-antigravity. Antigravity supports /acp mode, /model, and /thinking before a prompt, with the agent confirming selections before pi saves them. |
Has none of them | Subscription providers |
ACP agents as providers: Kiro CLI (V3), Amp, and the agents of the ACP registry run over stdio with their own tools. /acp installs them from the registry in the global or project settings, logs in, enables, disables, moves, and sets the default. The acpAgents setting stores them. They get pi's MCP servers, their slash commands complete in the editor, and /undo covers their file changes. |
Has no ACP client | ACP agents |
The global disabledProviders setting hides providers from model selection and keeps their credentials. The TUI /settings menu has a Disabled providers list. |
Disable providers | |
The global rememberLastModel setting (on by default, Remember last model in /settings) saves each model you switch to as the default: a /model selector pick, /model <provider>/<id>, RPC set_model and cycle_model, and ACP model changes. Model cycling with Ctrl+P saves it with either setting. |
Saves the default model only with the selector's set-as-default key. Does not save on /model <provider>/<id>, RPC, or model cycling. |
Remember the last model |
/settings items for the retry.* and retry.provider.* values |
Sets these values only in settings.json |
Retry settings |
listOverflow and List overflow in /settings: truncate, wrap, or scroll long list rows; PI_REDUCED_MOTION=1 disables scrolling |
Truncates list rows | List overflow |
| A terminal notification when a run takes 10 seconds or more | Has this only as the example extension notify.ts |
Notifications |
The status line and /statusline are the marketplace:statusline extension (pi install marketplace:statusline). It reads the legacy statusLine setting. Interactive mode offers to install it when statusLine is set. |
Changes the footer only through extensions | Status line |
| More harness themes | Themes | |
The iTerm2 integration and /terminal-setup are the marketplace:iterm2 extension (pi install marketplace:iterm2). It reads the legacy terminal.iterm2 setting. Interactive mode offers to install it when terminal.iterm2 is on. |
iTerm2 integration | |
Extension UI calls: ctx.ui.writeTerminal(data, { tmuxPassthrough }) writes raw bytes to the terminal. Footer data of ctx.ui.setFooter also has getSessionStats() (input, output, cacheRead, cacheWrite, cost, contextTokens, contextWindow, contextPercent) and getRunState() (idle, working, blocked, done, or error). |
Has none of them | |
Native extensions: a package lists programs in package.json pi.native, and pi runs each one as an extension over a JSON-RPC protocol on stdio |
Loads only TypeScript and JavaScript extensions | Native extension protocol |
Extensions call a tool of an MCP server of the session outside of a tool call, for example for a hook: pi.callMcpTool(server, tool, args) and the native method mcp.callTool |
Has no MCP tool calls for extensions | mcp.callTool |
Extension events for hook runners: instructions_loaded, prompt_expansion (can block a skill or template prompt or add context), notification, tool_call_blocked, cwd_changed, and before_provider_auth (sends a request with another login of the model's provider, such as a second subscription account). session_start handlers can call ctx.switchSession(). |
Has none of these events. Only command contexts have switchSession. |
pi-rust events |
Native extensions draw the rows of tools without renderers, such as the built-in tools (toolRenderers), animate a spinner inside drawn rows, refresh rows on a timer, read the TUI theme (ui.getTheme, theme.changed), and set the working indicator. ctx.ui.setChatStyle (ui.setChatStyle) puts prefixes before user and assistant messages, collapses finished thinking, and rounds the editor |
Renderers | |
ctx.ui.setChatStyle also sets the editor border color (editorBorderColor: a theme color token or #rrggbb, in place of the thinking level color) and the prompt layout (promptLayout: frame, caret for a rounded box with a › gutter and a placeholder, or harbor for a caret box with plain border rules) |
Chat style | |
An expanded tool row can show an extension's view of the result (pi.registerToolResultExpander, native toolResultExpander and render.toolResultExpanded), for example the full text behind a shortened result. pi shows at most maxHeight lines with a position line, and the mouse wheel scrolls the view in fullscreen mode |
Has no expander for other tools' results | Renderers |
Native extensions write their own top-level settings key in the global or a trusted project settings.json with settings.set. pi refuses its own setting keys. |
Extensions have no settings write | settings.set |
pi.registerProvider takes oauth: { builtin: "<provider id>", name? }: the provider logs in and refreshes with a login flow of pi, and stores the credential under its own id |
Reuses a flow only through an imported OAuth object | provider.register |
Extension widgets above and below the editor share a budget of a third of the terminal rows. Over the budget, each widget shows its first line. Alt+W (app.widgets.toggle) and /widgets collapse, expand, or auto change this, and /widgets shows all widgets in full in the chat. |
Caps only text widgets, at 10 lines each | /widgets |
MCP servers with "lifecycle": "lazy" in mcp.json (per server or as the top-level default) connect on first use. pi saves each server's tool list in mcp-cache/ in the agent directory, so a lazy server's tools are known before it connects. /mcp and pi mcp add --lifecycle set it. |
Connects every enabled server when the session starts | MCP server lifecycle |
MCP elicitation: servers can ask the user for form data or to open a URL. The extension events mcp_elicitation and mcp_elicitation_result can answer a request or change the answer of the user. |
Has no MCP elicitation | MCP elicitation events |
The extension event message_display replaces the text of an assistant message on the screen in the TUI. The session and the model context keep the original text. JavaScript and native extensions can listen to it. |
Has no display-only event. registerMarkdownTransformer changes the Markdown at each render. |
Events |
Deferred context: the contextExposure setting and the skill frontmatter exposure: deferred keep skills and extension context entries, such as agent configs, out of the system prompt. tool_search finds them and returns how to load or use them. Extensions add entries with contextEntries in their resources_discover result. |
Lists every skill in the system prompt. Only tools can be deferred. | Deferred context |
A choice of extension engine: the extensionRuntime setting, --extension-runtime, and PI_EXTENSION_RUNTIME (quickjs, node, or auto) |
Always runs extensions on Node | Extension runtime |
pi-rust MCP questions
Does pi-rust require Node.js?
No, pi-rust does not need Node.js or a different JavaScript runtime because it uses an embedded QuickJS engine for extensions.
Can I use pi-rust with different LLM providers?
Yes, it includes a streaming API for large language models from many providers, including Anthropic, OpenAI, and Gemini.
How do I manage MCP servers in pi-rust?
You can configure MCP servers in the ~/.pi/agent/mcp.json or <project>/.pi/mcp.json files.