Release notes and changes from the Pi changelog.
New version of pi. Download from npm or view release on GitHub.
ctx.switchSession(sessionPath). See docs/extensions.md. (#1187)terminal.clearOnShrink setting keeps the editor and footer pinned to the bottom of the terminal when content shrinks. May cause some flicker due to redraws. Disabled by default. Enable via /settings or PI_CLEAR_ON_SHRINK=1 env var.New version of pi. Download from npm or view release on GitHub.
ToolDefinition.execute now uses (toolCallId, params, signal, onUpdate, ctx) parameter order to match AgentTool.execute. Previously it was (toolCallId, params, onUpdate, ctx, signal). This makes wrapping built-in tools trivial since the first four parameters now align. Update your extensions by swapping the signal and onUpdate parameters:// Before
async execute(toolCallId, params, onUpdate, ctx, signal) { ... }
// After
async execute(toolCallId, params, signal, onUpdate, ctx) { ... }
pkg install nodejs termux-api git
npm install -g @mariozechner/pi-coding-agent
mkdir -p ~/.pi/agent
echo "You are running on Android in Termux." > ~/.pi/agent/AGENTS.md
termux-api is unavailable. (#1164)pi.setBashSpawnHook(). Adjust the command string, working directory, or environment variables. See docs/extensions.md. (#1160 by @mitsuhiko)PI_PACKAGE_DIR environment variable overrides the package path for content-addressed package managers where store paths tokenize poorly. See README.md#environment-variables. (#1153 by @odysseus0)/resume picker now supports filtering to show only named sessions via Ctrl+N. Configurable via toggleSessionNamedFilter keybinding. See docs/keybindings.md. (#1128 by @w-winter)ToolCallEvent types using isToolCallEventType() for better TypeScript support. See docs/extensions.md#tool-call-events. (#1147 by @giuseppeg)ToolCallEvent.input per tool with isToolCallEventType() type guard for narrowing built-in tool events (#1147 by @giuseppeg)discoverAndLoadExtensions from package to enable extension testing without a local repo clone (#1148)rpc-demo.ts example extension exercising all RPC-supported extension UI methods (#1144 by @aliou)rpc-extension-ui.ts TUI example client demonstrating the extension UI protocol with interactive dialogs (#1144 by @aliou)PI_PACKAGE_DIR environment variable to override package path for content-addressed package managers (Nix, Guix) where store paths tokenize poorly (#1153 by @odysseus0)/resume session picker now supports named-only filter toggle (default Ctrl+N, configurable via toggleSessionNamedFilter) to show only named sessions (#1128 by @w-winter)New version of pi. Download from npm or view release on GitHub.
titlebar-spinner.ts example extension that shows a braille spinner animation in the terminal title while the agent is working.PI_AI_ANTIGRAVITY_VERSION environment variable documentation to help text (#1129)cacheRetention stream option with provider-specific mappings for prompt cache controls, defaulting to short retention (#1134)New version of pi. Download from npm or view release on GitHub.
newSession, tree, and fork keybinding actions for /new, /tree, and /fork commands. All unbound by default. (#1114 by @juanibiapina)retry.maxDelayMs setting to cap maximum server-requested retry delay. When a provider requests a longer delay (e.g., Google's "quota will reset after 5h"), the request fails immediately with an informative error instead of waiting silently. Default: 60000ms (60 seconds). (#1123)/resume session picker: new "Threaded" sort mode (now default) displays sessions in a tree structure based on fork relationships. Compact one-line format with message count and age on the right. (#1124 by @pasky)modifyModels hook support for extension-registered providers at registration time. (#940 by @4h9fbZ)enable_thinking. (#940 by @4h9fbZ)resources_discover extension hook to supply additional skills, prompts, and themes on startup and reload.New version of pi. Download from npm or view release on GitHub.
index.ts (or manifest-declared entries) are loaded from subdirectories, not helper modules. (#1102)New version of pi. Download from npm or view release on GitHub.
/copy command now works over remote connections using the OSC 52 terminal escape sequence. No more clipboard frustration when using pi over SSH. (#1069 by @gturkoglu)vercelGatewayRouting in models.json. (#1051 by @ben-vargas)set_session_name RPC command - Headless clients can now set the session display name programmatically. (#1075 by @dnouri)"none" option for doubleEscapeAction setting completely disables the double-escape shortcut. (#973 by @juanibiapina)doubleEscapeAction setting to disable double-escape behavior entirely (#973 by @juanibiapina)/copy now works over remote connections. (#1069 by @gturkoglu)vercelGatewayRouting in models.json (#1051 by @ben-vargas)set_session_name RPC command for headless clients to set session display name (#1075 by @dnouri)New version of pi. Download from npm or view release on GitHub.
KIMI_API_KEY environment variable. See README.md#kimi-for-coding.KIMI_API_KEY environment variable. See README.md#kimi-for-coding.New version of pi. Download from npm or view release on GitHub.
HF_TOKEN environment variable. See README.md#hugging-face.PI_CACHE_RETENTION=long enables 1-hour caching for Anthropic (vs 5min default) and 24-hour for OpenAI (vs in-memory default). Only applies to direct API calls. See README.md#prompt-caching.autocompleteMaxVisible setting (3-20 items, default 5) controls dropdown size. Adjust via /settings or settings.json.alt+b/alt+f for word navigation, ctrl+d for delete character forward. See docs/keybindings.md.get_commands: Headless clients can now list available commands programmatically. See docs/rpc.md.PI_CACHE_RETENTION environment variable to control cache TTL for Anthropic (5m vs 1h) and OpenAI (in-memory vs 24h). Set to long for extended retention. (#967)autocompleteMaxVisible setting for configurable autocomplete dropdown height (3-20 items, default 5) (#972 by @masonc15)/files command to list all file operations (read, write, edit) in the current sessionalt+b/alt+f for word navigation, ctrl+d for delete character forward (when editor has text) (#1043 by @jasonish)get_commands RPC method for headless clients to list available commands (#995 by @dnouri)New version of pi. Download from npm or view release on GitHub.
ctx.newSession({ setup }) now properly syncs agent state and renders messages after setup callback runs (#968)/reload/hotkeys output to title-case extension hotkeys (#969 by @Perlence)New version of pi. Download from npm or view release on GitHub.
/reload) of resources including AGENTS.md, SYSTEM.md, APPEND_SYSTEM.md, prompt templates, skills, themes, and extensions. See README.md#commands and README.md#context-files.pi.registerProvider() for proxies, custom endpoints, OAuth or SSO flows, and non-standard streaming APIs. See docs/custom-provider.md.openRouterRouting. See docs/providers.md#api-keys and docs/models.md.disable-model-invocation. See docs/skills.md#frontmatter.models.json headers can resolve environment variables and shell commands. See docs/models.md#value-resolution.--verbose CLI flag to override quiet startup. See README.md#cli-reference.Read the fully revamped docs in README.md, or have your clanker read them for you.
There are multiple SDK breaking changes since v0.49.3. For the quickest migration, point your agent at packages/coding-agent/docs/sdk.md, the SDK examples in packages/coding-agent/examples/sdk, and the SDK source in packages/coding-agent/src/core/sdk.ts and related modules.
models.json now resolve environment variables (if a header value matches an env var name, the env var value is used). This may change behavior if a literal header value accidentally matches an env var name. (#909)packages array in settings.json instead of extensions. Existing npm:/git: entries in extensions are auto-migrated. (#645)ResourceLoader only and settings.json uses arrays for extensions, skills, prompts, and themes (#645)discoverAuthStorage and discoverModels from the SDK. AuthStorage and ModelRegistry now default to ~/.pi/agent paths unless you pass an agentDir (#645)/resume picker via Ctrl+R without opening the session (#863 by @svkozak)disable-model-invocation frontmatter field for skills to prevent agentic invocation while still allowing explicit /skill:name commands (#927)copyToClipboard utility for extensions (#926 by @mitsuhiko)models.json now support environment variables and shell commands, matching apiKey resolution (#909)openRouterRouting compat field (#859 by @v01dpr1mr0s3)azure-openai-responses provider support for Azure OpenAI Responses API. (#890 by @markusylisiurunen)--verbose CLI flag to override quietStartup setting (#906 by @Perlence)markdown.codeBlockIndent setting to customize code block indentation in rendered outputpi install, pi remove, pi update, and pi list commands (#645)packages array (#645)"!funky.json", "*.ts") (#645)/reload command to reload extensions, skills, prompts, and themes (#645)pi config command with TUI to enable/disable package and top-level resources via patterns (#938)--skill, --prompt-template, --theme, --no-prompt-templates, and --no-themes (#645)ResourceDiagnostic type for all resource types (#645)pi.registerProvider() with streamSimple for custom API implementationscustom-provider.ts example extension demonstrating custom Anthropic provider with OAuth/resume picker sort toggle moved to Ctrl+S to free Ctrl+R for rename (#863 by @svkozak)/reload now re-renders the entire scrollback so updated extension components are visible immediately (#928 by @ferologics)New version of pi. Download from npm or view release on GitHub.
markdown.codeBlockIndent setting to customize code block indentation in rendered output (#855 by @terrorobe)inline-bash.ts example extension for expanding !{command} patterns in prompts (#881 by @scutifer)antigravity-image-gen.ts example extension for AI image generation via Google Antigravity (#893 by @ben-vargas)PI_SHARE_VIEWER_URL environment variable for custom share viewer URLs (#889 by @andresaraujo)l to Shift+L so users can search for entries containing "l" (#861 by @mitsuhiko)New version of pi. Download from npm or view release on GitHub.
widgetPlacement in pi.addWidget() (#850 by @marckrenn)AWS_CONTAINER_CREDENTIALS_RELATIVE_URI, AWS_CONTAINER_CREDENTIALS_FULL_URI, AWS_WEB_IDENTITY_TOKEN_FILE (#848)/settings (#847 by @unexge)strictResponsesPairing compat option from models.json schema (no longer needed)New version of pi. Download from npm or view release on GitHub.
strictResponsesPairing compat option for custom OpenAI Responses models on Azure (#768 by @prateekmedia)/resume) now supports path display toggle (Ctrl+P) and session deletion (Ctrl+D) with inline confirmation (#816 by @w-winter)#) instead of query strings (?) to prevent session IDs from being sent to buildwithpi.ai (#829 by @terrorobe)models.json can now be retrieved via shell command using ! prefix (e.g., "apiKey": "!security find-generic-password -ws 'anthropic'" for macOS Keychain) (#762 by @cv)New version of pi. Download from npm or view release on GitHub.
pi.setLabel(entryId, label) in ExtensionAPI for setting per-entry labels from extensions (#806)keyHint, appKeyHint, editorKey, appKey, rawKeyHint for extensions to format keybinding hints consistently (#802 by @dannote)VERSION from the package index and updated the custom-header example. (#798 by @tallshort)showHardwareCursor setting to control cursor visibility while still positioning it for IME support. (#800 by @ghoulr)ctx.compact() and ctx.getContextUsage() to extension contexts for programmatic compaction and context usage checks.pi-internal:// path resolution from the read tool.New version of pi. Download from npm or view release on GitHub.
quietStartup setting to silence startup output (version header, loaded context info, model scope line). Changelog notifications are still shown. (#777 by @ribelo)editorPaddingX setting for horizontal padding in input editor (0-3, default: 0)shellCommandPrefix setting to prepend commands to every bash execution, enabling alias expansion in non-interactive shells (e.g., "shellCommandPrefix": "shopt -s expand_aliases") (#790 by @richardgill)getArgumentCompletions in pi.registerCommand() (#775 by @ribelo)getShellConfig for extensions to detect user's shell environment (#766 by @dannote)thinkingText and selectedBg to theme schema (#763 by @scutifer)navigateTree() now supports replaceInstructions option to replace the default summarization prompt entirely, and label option to attach a label to the branch summary entry (#787 by @mitsuhiko)PI_HARDWARE_CURSOR=1 to enable (replaces PI_NO_HARDWARE_CURSOR=1 which disabled it).New version of pi. Download from npm or view release on GitHub.
Editor directly must now pass TUI as the first constructor argument: new Editor(tui, theme). The tui parameter is available in extension factory functions. (#732)gpt-5.1, gpt-5.2, gpt-5.1-codex-mini, gpt-5.2-codex). Features include static system prompt for OpenAI allowlisting, prompt caching via session ID, and reasoning signature retention across turns. Set OPENAI_API_KEY and use --provider openai-codex or select a Codex model. (#737)pi-internal:// URL scheme in read tool for accessing internal documentation. The model can read files from the coding-agent package (README, docs, examples) to learn about extending pi.input event in extension system for intercepting, transforming, or handling user input before the agent processes it. Supports three result types: continue (pass through), transform (modify text/images), handled (respond without LLM). Handlers chain transforms and short-circuit on handled. (#761 by @nicobailon)input-transform.ts demonstrating input interception patterns (quick mode, instant commands, source routing) (#761 by @nicobailon)renderCall/renderResult now render in /share and /export output with ANSI-to-HTML color conversion (#702 by @aliou)/skill:name) are now expanded in AgentSession instead of interactive mode. This enables skill commands in RPC and print modes, and allows the input event to intercept /skill:name before expansion.New version of pi. Download from npm or view release on GitHub.
APPEND_SYSTEM.md to append instructions to the system prompt (#716 by @tallshort)re: regex mode (#731 by @ogulcancelik)getAgentDir for extensions (#749 by @dannote)minimax-cn) provider support (#725 by @tallshort)gpt-5.2-codex models for GitHub Copilot and OpenCode Zen providers (#734 by @aadishv)wasm-vips with @silvia-odwyer/photon-node for image processing (#710 by @can1357)plan-mode/ shortcut changed from Shift+P to Ctrl+Alt+P to avoid conflict with typing capital P (#746 by @ferologics)pi for easier process identification (#742 by @richardgill)New version of pi. Download from npm or view release on GitHub.
ctx.ui.custom() now accepts overlayOptions for overlay positioning and sizing (anchor, margins, offsets, percentages, absolute positioning) (#667 by @nicobailon)ctx.ui.custom() now accepts onHandle callback to receive the OverlayHandle for controlling overlay visibility (#667 by @nicobailon)overlay-qa-tests.ts with 10 commands for testing overlay positioning, animation, and toggle scenarios (#667 by @nicobailon)doom-overlay/ - DOOM game running as an overlay at 35 FPS (auto-downloads WAD on first run) (#667 by @nicobailon)