News

• Subagent orchestration example: Added comprehensive custom tool example for spawning and orchestrating sub-agents with isolated context windows. Includes scout/planner/reviewer/worker agents and workflow commands for multi-agent pipelines. (#215 by @nicobailon)

• getMarkdownTheme() export: Custom tools can now import getMarkdownTheme() from @mariozechner/pi-coding-agent to use the same markdown styling as the main UI.

• pi.exec() signal and timeout support: Custom tools and hooks can now pass { signal, timeout } options to pi.exec() for cancellation and timeout handling. The result includes a killed flag when the process was terminated.

• Kitty keyboard protocol support: Shift+Enter, Alt+Enter, Shift+Tab, Ctrl+D, and all Ctrl+key combinations now work in Ghostty, Kitty, WezTerm, and other modern terminals. (#225 by @kim0)

• Dynamic API key refresh: OAuth tokens (GitHub Copilot, Anthropic OAuth) are now refreshed before each LLM call, preventing failures in long-running agent loops where tokens expire mid-session. (#223 by @kim0)

• /hotkeys command: Shows all keyboard shortcuts in a formatted table.

• Markdown table borders: Tables now render with proper top and bottom borders.

• Subagent example improvements: Parallel mode now streams updates from all tasks. Chain mode shows all completed steps during streaming. Expanded view uses proper markdown rendering with syntax highlighting. Usage footer shows turn count.

• Skills standard compliance: Skills now adhere to the Agent Skills standard. Validates name (must match parent directory, lowercase, max 64 chars), description (required, max 1024 chars), and frontmatter fields. Warns on violations but remains lenient. Prompt format changed to XML structure. Removed {baseDir} placeholder in favor of relative paths. (#231)

• Custom tools now require index.ts entry point: Auto-discovered custom tools must be in a subdirectory with an index.ts file. The old pattern ~/.pi/agent/tools/mytool.ts must become ~/.pi/agent/tools/mytool/index.ts. This allows multi-file tools to import helper modules. Explicit paths via --tool or settings.json still work with any .ts file.

• Hook tool_result event restructured: The ToolResultEvent now exposes full tool result data instead of just text. (#233)

  • Removed: result: string field
  • Added: content: (TextContent | ImageContent)[] - full content array
  • Added: details: unknown - tool-specific details (typed per tool via discriminated union on toolName)
  • ToolResultEventResult.result renamed to ToolResultEventResult.text (removed), use content instead
  • Hook handlers returning { result: "..." } must change to { content: [{ type: "text", text: "..." }] }
  • Built-in tool details types exported: BashToolDetails, ReadToolDetails, GrepToolDetails, FindToolDetails, LsToolDetails, TruncationResult
  • Type guards exported for narrowing: isBashToolResult, isReadToolResult, isEditToolResult, isWriteToolResult, isGrepToolResult, isFindToolResult, isLsToolResult

• Syntax highlighting: Added syntax highlighting for markdown code blocks, read tool output, and write tool content. Uses cli-highlight with theme-aware color mapping and VS Code-style syntax colors. (#214 by @svkozak)

• Intra-line diff highlighting: Edit tool now shows word-level changes with inverse highlighting when a single line is modified. Multi-line changes show all removed lines first, then all added lines.

• Improved system prompt documentation section with clearer pointers to specific doc files for custom models, themes, skills, hooks, custom tools, and RPC.

• Cleaned up documentation:

  • theme.md: Added missing color tokens (thinkingXhigh, bashMode)
  • skills.md: Rewrote with better framing and examples
  • hooks.md: Fixed timeout/error handling docs, added import aliases section
  • custom-tools.md: Added intro with use cases and comparison table
  • rpc.md: Added missing hook_error event documentation
  • README.md: Complete settings table, condensed philosophy section, standardized OAuth docs

• Hooks loader now supports same import aliases as custom tools (@sinclair/typebox, @mariozechner/pi-ai, @mariozechner/pi-tui, @mariozechner/pi-coding-agent).

• Hooks: turn_end event's toolResults type changed from AppMessage[] to ToolResultMessage[]. If you have hooks that handle turn_end events and explicitly type the results, update your type annotations.

• Fixed Claude models via GitHub Copilot re-answering all previous prompts in multi-turn conversations. The issue was that assistant message content was sent as an array instead of a string, which Copilot's Claude adapter misinterpreted. Also added missing Openai-Intent: conversation-edits header and fixed X-Initiator logic to check for any assistant/tool message in history. (#209)

• Detect image MIME type via file magic (read tool and @file attachments), not filename extension.

• Fixed markdown tables overflowing terminal width. Tables now wrap cell contents to fit available width instead of breaking borders mid-row. (#206 by @kim0)

• Fixed TUI performance regression caused by Box component lacking render caching. Built-in tools now use Text directly (like v0.22.5), and Box has proper caching for custom tool rendering.

• Fixed custom tools failing to load from ~/.pi/agent/tools/ when pi is installed globally. Module imports (@sinclair/typebox, @mariozechner/pi-tui, @mariozechner/pi-ai) are now resolved via aliases.

• Custom tools: Extend pi with custom tools written in TypeScript. Tools can provide custom TUI rendering, interact with users via pi.ui (select, confirm, input, notify), and maintain state across sessions via onSession callback. See docs/custom-tools.md and examples/custom-tools/. (#190)

• Hook and tool examples: Added examples/hooks/ and examples/custom-tools/ with working examples. Examples are now bundled in npm and binary releases.

• Hooks: Replaced session_start and session_switch events with unified session event. Use event.reason ("start" | "switch" | "clear") to distinguish. Event now includes entries array for state reconstruction.

• Fixed --session flag not saving sessions in print mode (-p). The session manager was never receiving events because no subscriber was attached.

• --list-models [search] CLI flag to list available models with optional fuzzy search. Shows provider, model ID, context window, max output, thinking support, and image support. Only lists models with configured API keys. (#203)

• Streaming bash output: Bash tool now streams output in real-time during execution. The TUI displays live progress with the last 5 lines visible (expandable with ctrl+o). (#44)

• Tool output display: When collapsed, tool output now shows the last N lines instead of the first N lines, making streaming output more useful.

• Updated @mariozechner/pi-ai with X-Initiator header support for GitHub Copilot, ensuring agent calls are not deducted from quota. (#200 by @kim0)

• Updated @mariozechner/pi-ai with interleaved thinking enabled by default for Anthropic Claude 4 models.

Dedicated to Peter's shoulder (@steipete)

• Updated @mariozechner/pi-ai with interleaved thinking support for Anthropic models.

• GitHub Copilot support: Use GitHub Copilot models via OAuth login (/login -> "GitHub Copilot"). Supports both github.com and GitHub Enterprise. Models are sourced from models.dev and include Claude, GPT, Gemini, Grok, and more. All models are automatically enabled after login. (#191 by @cau1k)

• Inline image rendering: Terminals supporting Kitty graphics protocol (Kitty, Ghostty, WezTerm) or iTerm2 inline images now render images inline in tool output. Aspect ratio is preserved by querying terminal cell dimensions on startup. Toggle with /show-images command or terminal.showImages setting. Falls back to text placeholder on unsupported terminals or when disabled. (#177 by @nicobailon)

• Gemini 3 Pro thinking levels: Thinking level selector now works with Gemini 3 Pro models. Minimal/low map to Google's LOW, medium/high map to Google's HIGH. (#176 by @markusylisiurunen)

• Exported skills API: loadSkillsFromDir, formatSkillsForPrompt, and related types are now exported for use by other packages (e.g., mom).

• Pi skills now use SKILL.md convention: Pi skills must now be named SKILL.md inside a directory, matching Codex CLI format. Previously any *.md file was treated as a skill. Migrate by renaming ~/.pi/agent/skills/foo.md to ~/.pi/agent/skills/foo/SKILL.md.

• Display loaded skills on startup in interactive mode

• Documentation: Added skills system documentation to README (setup, usage, CLI flags, settings)

• Skills system: Auto-discover and load instruction files on-demand. Supports Claude Code (~/.claude/skills/*/SKILL.md), Codex CLI (~/.codex/skills/), and Pi-native formats (~/.pi/agent/skills/, .pi/skills/). Skills are listed in system prompt with descriptions, agent loads them via read tool when needed. Supports {baseDir} placeholder. Disable with --no-skills or skills.enabled: false in settings. (#169)

• Version flag: Added --version / -v flag to display the current version and exit. (#170)

• Auto-retry on transient errors: Automatically retries requests when providers return overloaded, rate limit, or server errors (429, 500, 502, 503, 504). Uses exponential backoff (2s, 4s, 8s). Shows retry status in TUI with option to cancel via Escape. Configurable in settings.json via retry.enabled, retry.maxRetries, retry.baseDelayMs. RPC mode emits auto_retry_start and auto_retry_end events. (#157)

• HTML export line numbers: Read tool calls in HTML exports now display line number ranges (e.g., file.txt:10-20) when offset/limit parameters are used, matching the TUI display format. Line numbers appear in yellow color for better visibility. (#166)

• Mistral provider: Added support for Mistral AI models. Set MISTRAL_API_KEY environment variable to use.

• Hooks system: TypeScript modules that extend agent behavior by subscribing to lifecycle events. Hooks can intercept tool calls, prompt for confirmation, modify results, and inject messages from external sources. Auto-discovered from ~/.pi/agent/hooks/*.ts and .pi/hooks/*.ts. Thanks to @nicobailon for the collaboration on the design and implementation. (#145, supersedes #158)

• pi.send() API: Hooks can inject messages into the agent session from external sources (file watchers, webhooks, CI systems). If streaming, messages are queued; otherwise a new agent loop starts immediately.

• --hook <path> CLI flag: Load hook files directly for testing without modifying settings.

• Hook events: session_start, session_switch, agent_start, agent_end, turn_start, turn_end, tool_call (can block), tool_result (can modify), branch.

• Hook UI primitives: ctx.ui.select(), ctx.ui.confirm(), ctx.ui.input(), ctx.ui.notify() for interactive prompts from hooks.

• Hooks documentation: Full API reference at docs/hooks.md, shipped with npm package.