Differences from upstream pi
What pi-rust adds to the TypeScript pi, where its runtime behaves differently, and which upstream bugs it already fixes.
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.- For a mainland China login, set
KIMI_CODE_OAUTH_HOST=https://auth.kimi.com. - A new login stores its OAuth and API endpoints for later refreshes. Older logins without this metadata keep their mainland endpoints.
KIMI_CODE_OAUTH_HOSTandKIMI_CODE_BASE_URL, when set, override the saved endpoints. A custom modelbaseUrlinmodels.jsonstays in effect.
- For a mainland China login, set
-
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(). 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. -
In extensions,
ctx.sessionManagerreads return copies of entries, exceptgetEntries()of the extension’s own session. Upstream pi returns its own entry objects from all reads.- As in upstream pi,
getEntries()of the extension’s own session returns the same entry objects on each call, and a message entry holds the message object that themessage_endhandlers received. Thecontextofturn_endandagent_before_settleholds these objects too. - The other reads, such as
getEntry()andgetBranch(), return new copies on each call. Changes to returned entries do not change the session.
- As in upstream pi,
-
The extension SDK still has gaps in child sessions, resource loading, and model runtimes.
- A
DefaultResourceLoaderwith extensions serves one child session for eachreload(). Its factories run in the caller’s extension host. SettingsManagersupports custom storage and queued writes, with limits on JSON values and live object references.
See Extension module exports for the remaining differences.
- A
-
pi.registerProvider(provider)with an upstreamProviderobject, which hasgetModels()and no stringapi, registers nothing and reports aregister_providererror. Usepi.registerProvider(name, { api, baseUrl, models, streamSimple }). An object withidand a stringapiregisters as that config. See Extension module exports. -
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, including 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. -
An abort finishes in less than a second. Upstream pi waits for every tool and handler.
- The running tools and the extension handlers of the run’s last events share 400 ms. Slow handlers keep running without blocking.
- RPC
abortanswers within 1.5 s. - A prompt sent while a run aborts starts after the run ends. Upstream pi rejects it.
- Extension prompts that were waiting to start do not run. Upstream pi starts them.
See RPC mode.
-
grepandfinduse the Rustignorecrate, so pi-rust does not downloadrgorfd. -
The version check and
pi update --selfuse the releases of this repository. -
/bugoffers Upload Report, Open GitHub Issue, and Export as Zip. Upload Report sends the report privately topi-rust.com(PI_BUG_REPORT_URLoverrides it). Open GitHub Issue writes the zip archive and opens a public prefilled issue form onyannelli/pi-rust; you submit it and attach the zip yourself. Upstream pi uploads the report to its Radius gateway (radius.pi.dev). -
Word movement in Chinese, Japanese, Korean (CJK), and Thai text uses ICU4X dictionaries, so some word boundaries differ 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 stops waiting for output as upstream does: 100 ms after the exit, or 100 ms after the last chunk that follows the exit. Then:
- It delivers the queued chunks and any chunk that the readers finish reading before they observe the stop signal.
- On Unix, it also takes at most 64 KiB more per stream, if that data is readable without waiting.
- On Windows, it starts no further read.
See Platform.
-
When you clear the message queue, pi removes only your queued messages. Upstream pi drops queued extension messages with the queue.
- Esc while the agent works, the dequeue key, and the RPC
clear_queuecommand clear the queue. - 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 that an extension sends with
triggerTurnwhile the run is ending continues that run. Upstream pi leaves that message queued until the next prompt.
- Esc while the agent works, the dequeue key, and the RPC
-
In a linked git worktree, pi reads the project files that the worktree lacks from the main checkout. Upstream pi reads only the worktree.
- Files:
.pi/settings.json,.pi/mcp.json,.pi/SYSTEM.md, and.pi/APPEND_SYSTEM.md. - Folders:
.pi/skills,.pi/prompts,.pi/extensions, and.pi/themes. - 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.
See Settings.
- Files:
-
Extension and login
selectmenus show at most 10 options, with a(n/total)counter, so the selected option stays visible. Short terminals show fewer options. 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 |
Ctrl+Enter (app.message.interrupt) stops the agent, also during a long tool call, and sends the queued messages and the editor text as one prompt |
Needs Esc, which moves the queue to the editor, and then Enter | Interactive commands |
| Esc clears the input draft when the agent is idle. 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, pi extensions search, and pi extensions info, which 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, with several sessions per connection and the client’s stdio and HTTP MCP servers |
Needs the separate pi-acp adapter. pi-acp accepts no HTTP MCP servers, keeps one session per connection, rejects a prompt while pi runs on its own, and ends failed turns with end_turn. |
ACP mode |
RPC and ACP modes run /usage, /context, /extensions, /fast, and /reload without a model call. RPC mode also runs /session, /changelog, /export, and /name. |
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 |
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 subscription providers cursor and google-antigravity |
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 and manages them. |
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) saves each model you switch to as the default |
Saves the default model only with the selector’s set-as-default key | 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, as the marketplace:statusline extension |
Changes the footer only through extensions | Status line |
| More harness themes | Themes | |
The iTerm2 integration and /terminal-setup, as the marketplace:iterm2 extension |
iTerm2 integration | |
The extension UI call ctx.ui.writeTerminal(data, { tmuxPassthrough }) writes raw bytes to the terminal |
Has no such call | |
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 neither | |
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 tools of the session’s MCP servers outside a tool call, for example from 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, notification, tool_call_blocked, cwd_changed, and before_provider_auth. session_start handlers can call ctx.switchSession(). |
Has none of these events. Only command contexts have switchSession. |
pi-rust events |
A session_before_compact result can set customInstructions for that compaction. The text replaces the instructions of the event, so a handler that keeps them adds its text to event.customInstructions. |
Reads only cancel and compaction |
Events |
Native extensions draw the rows of tools without renderers, such as the built-in tools (toolRenderers). They can also animate a spinner inside drawn rows, refresh rows on a timer, read the TUI theme, and set the working indicator. |
Renderers | |
ctx.ui.setChatStyle (ui.setChatStyle) puts prefixes before user and assistant messages, collapses finished thinking, and rounds the editor. It also sets the editor border color and the prompt layout (frame, caret, or harbor). |
Chat style | |
An expanded tool row can show an extension’s view of the result (pi.registerToolResultExpander, native toolResultExpander), for example the full text behind a shortened result |
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. | Caps only text widgets, at 10 lines each | /widgets |
MCP servers with "lifecycle": "lazy" in mcp.json connect on first use. A saved tool list makes their tools known before they connect. |
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. |
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. |
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 |
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). modelOverridesinmodels.jsonalso apply to classifier and image models:name,input,inputLimits, andcost. For classifiers,contextWindowandcompatalso 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
toolsorconsole(11226). - Branch summaries from
/treeuse 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 withsendUserMessageruns before pi exits (11238). - An unpinned
-e npm:package updates when npm has a newer version (11375). pi.execkeeps a maximum of 16 MiB of output from a command. It stops the command when the output gets to that limit (11360).pi-envwatches a directory again after the kernel drops the watch and the directory keeps its inode (11342).