News

• Multi-file extensions in packages now work correctly. Package resolution now uses the same discovery logic as local extensions: only index.ts (or manifest-declared entries) are loaded from subdirectories, not helper modules. (#1102)

• Added ctx.getSystemPrompt() to extension context for accessing the current effective system prompt (#1098 by @kaofelix)

• OSC 52 clipboard support for SSH/mosh - The /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)
• Vercel AI Gateway routing - Route requests through Vercel's AI Gateway with provider failover and load balancing. Configure via vercelGatewayRouting in models.json. (#1051 by @ben-vargas)
• Character jump navigation - Bash/Readline-style character search: Ctrl+] jumps forward to the next occurrence of a character, Ctrl+Alt+] jumps backward. (#1074 by @Perlence)
• Emacs-style Ctrl+B/Ctrl+F navigation - Alternative keybindings for word navigation (cursor word left/right) in the editor. (#1053 by @ninlds)
• Line boundary navigation - Editor jumps to line start when pressing Up at first visual line, and line end when pressing Down at last visual line. (#1050 by @4h9fbZ)
• Performance improvements - Optimized image line detection and box rendering cache in the TUI for better rendering performance. (#1084 by @can1357)
• set_session_name RPC command - Headless clients can now set the session display name programmatically. (#1075 by @dnouri)
• Disable double-escape behavior - New "none" option for doubleEscapeAction setting completely disables the double-escape shortcut. (#973 by @juanibiapina)

• Added "none" option to doubleEscapeAction setting to disable double-escape behavior entirely (#973 by @juanibiapina)
• Added OSC 52 clipboard support for SSH/mosh sessions. /copy now works over remote connections. (#1069 by @gturkoglu)
• Added Vercel AI Gateway routing support via vercelGatewayRouting in models.json (#1051 by @ben-vargas)
• Added Ctrl+B and Ctrl+F keybindings for cursor word left/right navigation in the editor (#1053 by @ninlds)
• Added character jump navigation: Ctrl+] jumps forward to next character, Ctrl+Alt+] jumps backward (#1074 by @Perlence)
• Editor now jumps to line start when pressing Up at first visual line, and line end when pressing Down at last visual line (#1050 by @4h9fbZ)
• Optimized image line detection and box rendering cache for better TUI performance (#1084 by @can1357)
• Added set_session_name RPC command for headless clients to set session display name (#1075 by @dnouri)

• Kimi For Coding provider: Access Moonshot AI's Anthropic-compatible coding API. Set KIMI_API_KEY environment variable. See README.md#kimi-for-coding.

• Added Kimi For Coding provider support (Moonshot AI's Anthropic-compatible coding API). Set KIMI_API_KEY environment variable. See README.md#kimi-for-coding.

• Hugging Face provider: Access Hugging Face models via OpenAI-compatible Inference Router. Set HF_TOKEN environment variable. See README.md#hugging-face.
• Extended prompt caching: 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.
• Configurable autocomplete height: autocompleteMaxVisible setting (3-20 items, default 5) controls dropdown size. Adjust via /settings or settings.json.
• Shell-style keybindings: alt+b/alt+f for word navigation, ctrl+d for delete character forward. See docs/keybindings.md.
• RPC get_commands: Headless clients can now list available commands programmatically. See docs/rpc.md.

• Added Hugging Face provider support via OpenAI-compatible Inference Router (#994)
• Added 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)
• Added autocompleteMaxVisible setting for configurable autocomplete dropdown height (3-20 items, default 5) (#972 by @masonc15)
• Added /files command to list all file operations (read, write, edit) in the current session
• Added shell-style keybindings: alt+b/alt+f for word navigation, ctrl+d for delete character forward (when editor has text) (#1043 by @jasonish)
• Added get_commands RPC method for headless clients to list available commands (#995 by @dnouri)

• Improved extractCursorPosition performance in TUI: scans lines in reverse order, early-outs when cursor is above viewport (#1004 by @can1357)
• Autocomplete improvements: better handling of partial matches and edge cases (#1024 by @Perlence)

• Git extension updates now handle force-pushed remotes gracefully instead of failing (#961 by @aliou)
• Extension ctx.newSession({ setup }) now properly syncs agent state and renders messages after setup callback runs (#968)
• Fixed extension UI bindings not initializing when starting with no extensions, which broke UI methods after /reload
• Fixed /hotkeys output to title-case extension hotkeys (#969 by @Perlence)
• Fixed model catalog generation to exclude deprecated OpenCode Zen models (#970 by @DanielTatarkin)
• Fixed git extension removal to prune empty directories

• Pi packages for bundling and installing extensions, skills, prompts, and themes. See docs/packages.md.
• Hot reload (/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.
• Custom providers via pi.registerProvider() for proxies, custom endpoints, OAuth or SSO flows, and non-standard streaming APIs. See docs/custom-provider.md.
• Azure OpenAI Responses provider support with deployment-aware model mapping. See docs/providers.md#azure-openai.
• OpenRouter routing support for custom models via openRouterRouting. See docs/providers.md#api-keys and docs/models.md.
• Skill invocation messages are now collapsible and skills can opt out of model invocation via disable-model-invocation. See docs/skills.md#frontmatter.
• Session selector renaming and configurable keybindings. See README.md#commands and docs/keybindings.md.
• 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.

• Header values in 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)
• External packages (npm/git) are now configured via packages array in settings.json instead of extensions. Existing npm:/git: entries in extensions are auto-migrated. (#645)
• Resource loading now uses ResourceLoader only and settings.json uses arrays for extensions, skills, prompts, and themes (#645)
• Removed discoverAuthStorage and discoverModels from the SDK. AuthStorage and ModelRegistry now default to ~/.pi/agent paths unless you pass an agentDir (#645)

• Session renaming in /resume picker via Ctrl+R without opening the session (#863 by @svkozak)
• Session selector keybindings are now configurable (#948 by @aos)
• disable-model-invocation frontmatter field for skills to prevent agentic invocation while still allowing explicit /skill:name commands (#927)
• Exposed copyToClipboard utility for extensions (#926 by @mitsuhiko)
• Skill invocation messages are now collapsible in chat output, showing collapsed by default with skill name and expand hint (#894)
• Header values in models.json now support environment variables and shell commands, matching apiKey resolution (#909)
• Added HTTP proxy environment variable support for API requests (#942 by @haoqixu)
• Added OpenRouter provider routing support for custom models via openRouterRouting compat field (#859 by @v01dpr1mr0s3)
• Added azure-openai-responses provider support for Azure OpenAI Responses API. (#890 by @markusylisiurunen)
• Added changelog link to update notifications (#925 by @dannote)
• Added --verbose CLI flag to override quietStartup setting (#906 by @Perlence)
• markdown.codeBlockIndent setting to customize code block indentation in rendered output
• Extension package management with pi install, pi remove, pi update, and pi list commands (#645)
• Package filtering: selectively load resources from packages using object form in packages array (#645)
• Glob pattern support with minimatch in package filters, top-level settings arrays, and pi manifest (e.g., "!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)
• CLI flags for --skill, --prompt-template, --theme, --no-prompt-templates, and --no-themes (#645)
• Package deduplication: if same package appears in global and project settings, project wins (#645)
• Unified collision reporting with ResourceDiagnostic type for all resource types (#645)
• Show provider alongside the model in the footer if multiple providers are available
• Custom provider support via pi.registerProvider() with streamSimple for custom API implementations
• Added custom-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)
• HTML export: clicking a sidebar message now navigates to its newest leaf and scrolls to it, instead of truncating the branch (#853 by @mitsuhiko)
• HTML export: active path is now visually highlighted with dimmed off-path nodes (#929 by @hewliyang)
• Azure OpenAI Responses provider now uses base URL configuration with deployment-aware model mapping and no longer includes service tier handling
• /reload now re-renders the entire scrollback so updated extension components are visible immediately (#928 by @ferologics)
• Skill, prompt template, and theme discovery now use settings and CLI path arrays instead of legacy filters (#645)

• markdown.codeBlockIndent setting to customize code block indentation in rendered output (#855 by @terrorobe)
• Added inline-bash.ts example extension for expanding !{command} patterns in prompts (#881 by @scutifer)
• Added antigravity-image-gen.ts example extension for AI image generation via Google Antigravity (#893 by @ben-vargas)
• Added PI_SHARE_VIEWER_URL environment variable for custom share viewer URLs (#889 by @andresaraujo)
• Added Alt+Delete as hotkey for delete word forwards (#878 by @Perlence)

• Tree selector: changed label filter shortcut from l to Shift+L so users can search for entries containing "l" (#861 by @mitsuhiko)
• Fuzzy matching now scores consecutive matches higher for better search relevance (#860 by @mitsuhiko)

• Added widget placement option for extension widgets via widgetPlacement in pi.addWidget() (#850 by @marckrenn)
• Added AWS credential detection for ECS/Kubernetes environments: AWS_CONTAINER_CREDENTIALS_RELATIVE_URI, AWS_CONTAINER_CREDENTIALS_FULL_URI, AWS_WEB_IDENTITY_TOKEN_FILE (#848)
• Add "quiet startup" setting to /settings (#847 by @unexge)

• HTML export now includes JSONL download button, jump-to-last-message on click, and fixed missing labels (#853 by @mitsuhiko)
• Improved error message for OAuth authentication failures (expired credentials, offline) instead of generic 'No API key found' (#849 by @zedrdave)

• Removed strictResponsesPairing compat option from models.json schema (no longer needed)

• Added strictResponsesPairing compat option for custom OpenAI Responses models on Azure (#768 by @prateekmedia)
• Session selector (/resume) now supports path display toggle (Ctrl+P) and session deletion (Ctrl+D) with inline confirmation (#816 by @w-winter)
• Added undo support in interactive mode with Ctrl+- hotkey. (#831 by @Perlence)

• Share URLs now use hash fragments (#) instead of query strings (?) to prevent session IDs from being sent to buildwithpi.ai (#829 by @terrorobe)
• API keys in 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)

• pi.setLabel(entryId, label) in ExtensionAPI for setting per-entry labels from extensions (#806)
• Export keyHint, appKeyHint, editorKey, appKey, rawKeyHint for extensions to format keybinding hints consistently (#802 by @dannote)
• Exported VERSION from the package index and updated the custom-header example. (#798 by @tallshort)
• Added showHardwareCursor setting to control cursor visibility while still positioning it for IME support. (#800 by @ghoulr)
• Added Emacs-style kill ring editing with yank and yank-pop keybindings, plus legacy Alt+letter handling and Alt+D delete word forward support in the interactive editor. (#810 by @Perlence)
• Added ctx.compact() and ctx.getContextUsage() to extension contexts for programmatic compaction and context usage checks.
• Added documentation for delete word forward and kill ring keybindings in interactive mode. (#810 by @Perlence)

• Updated the default system prompt wording to clarify the pi harness and documentation scope.
• Simplified Codex system prompt handling to use the default system prompt directly for Codex instructions.

• Removed pi-internal:// path resolution from the read tool.

• Added quietStartup setting to silence startup output (version header, loaded context info, model scope line). Changelog notifications are still shown. (#777 by @ribelo)
• Added editorPaddingX setting for horizontal padding in input editor (0-3, default: 0)
• Added 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)
• Added bash-style argument slicing for prompt templates (#770 by @airtonix)
• Extension commands can provide argument auto-completions via getArgumentCompletions in pi.registerCommand() (#775 by @ribelo)
• Bash tool now displays the timeout value in the UI when a timeout is set (#780 by @dannote)
• Export getShellConfig for extensions to detect user's shell environment (#766 by @dannote)
• Added 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)

• Hardware cursor is now disabled by default for better terminal compatibility. Set PI_HARDWARE_CURSOR=1 to enable (replaces PI_NO_HARDWARE_CURSOR=1 which disabled it).

• Extensions using 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)

• OpenAI Codex official support: Full compatibility with OpenAI's Codex CLI models (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.
• New 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)
• Extension example: input-transform.ts demonstrating input interception patterns (quick mode, instant commands, source routing) (#761 by @nicobailon)
• Custom tool HTML export: extensions with renderCall/renderResult now render in /share and /export output with ANSI-to-HTML color conversion (#702 by @aliou)
• Direct filter shortcuts in Tree mode: Ctrl+D (default), Ctrl+T (no-tools), Ctrl+U (user-only), Ctrl+L (labeled-only), Ctrl+A (all) (#747 by @kaofelix)

• Skill commands (/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.

• Edit tool now uses fuzzy matching as fallback when exact match fails, tolerating trailing whitespace, smart quotes, Unicode dashes, and special spaces (#713 by @dannote)
• Support APPEND_SYSTEM.md to append instructions to the system prompt (#716 by @tallshort)
• Session picker search: Ctrl+R toggles sorting between fuzzy match (default) and most recent; supports quoted phrase matching and re: regex mode (#731 by @ogulcancelik)
• Export getAgentDir for extensions (#749 by @dannote)
• Show loaded prompt templates on startup (#743 by @tallshort)
• MiniMax China (minimax-cn) provider support (#725 by @tallshort)
• gpt-5.2-codex models for GitHub Copilot and OpenCode Zen providers (#734 by @aadishv)

• Replaced wasm-vips with @silvia-odwyer/photon-node for image processing (#710 by @can1357)
• Extension example: plan-mode/ shortcut changed from Shift+P to Ctrl+Alt+P to avoid conflict with typing capital P (#746 by @ferologics)
• UI keybinding hints now respect configured keybindings across components (#724 by @dannote)
• CLI process title is now set to pi for easier process identification (#742 by @richardgill)

• Exported highlightCode and getLanguageFromPath for extensions (#703 by @dannote)

• 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)
• Extension example: overlay-qa-tests.ts with 10 commands for testing overlay positioning, animation, and toggle scenarios (#667 by @nicobailon)
• Extension example: doom-overlay/ - DOOM game running as an overlay at 35 FPS (auto-downloads WAD on first run) (#667 by @nicobailon)

• Skip changelog display on fresh install (only show on upgrades)

• Light theme colors adjusted for WCAG AA compliance (4.5:1 contrast ratio against white backgrounds)
• Replaced sharp with wasm-vips for image processing (resize, PNG conversion). Eliminates native build requirements that caused installation failures on some systems. (#696)

• Extension example: summarize.ts for summarizing conversations using custom UI and an external model (#684 by @scutifer)
• Extension example: question.ts enhanced with custom UI for asking user questions (#693 by @ferologics)
• Extension example: plan-mode/ enhanced with explicit step tracking and progress widget (#694 by @ferologics)
• Extension example: questionnaire.ts for multi-question input with tab bar navigation (#695 by @ferologics)
• Experimental Vercel AI Gateway provider support: set AI_GATEWAY_API_KEY and use --provider vercel-ai-gateway. Token usage is currently reported incorrectly by Anthropic Messages compatible endpoint. (#689 by @timolins)

• Extensions now load correctly in compiled Bun binary using @mariozechner/jiti fork with virtualModules support. Bundled packages (@sinclair/typebox, @mariozechner/pi-tui, @mariozechner/pi-ai, @mariozechner/pi-coding-agent) are accessible to extensions without filesystem node_modules.

• /share now outputs buildwithpi.ai session preview URLs instead of pi.dev