FAQ

These answers cover Pi and this documentation project. Open a GitHub issue if your question is not listed.

Pi itself

What is Pi?

Pi is an open-source coding-agent toolkit. Its monorepo contains a model API, an agent runtime, a terminal UI, and the pi command-line application. The main npm packages are @earendil-works/pi-ai, @earendil-works/pi-agent-core, and @earendil-works/pi-coding-agent.

Pi 1.0 stabilizes the core and Coding Agent. The separate @earendil-works/pi-durable package is experimental and supports long-running applications; it does not replace the Coding Agent.

How is Pi different from Claude Code or Codex?

Pi keeps the core small and exposes customization through extensions, skills, prompt templates, themes, and packages. Claude Code and Codex have different built-in workflows and service integrations. Compare the products against the workflow, provider support, security model, and deployment constraints you need rather than treating them as interchangeable agents.

Which model providers does Pi support?

Pi registers built-in providers for Anthropic, OpenAI, Google, Bedrock, OpenRouter, several subscription endpoints, and other hosted or local services. It can also register a custom provider or an OpenAI-compatible server. See Integrate a model provider.

These selected models show how one catalog name can have several provider routes:

This is not the complete catalog. Use /model or pi --list-models for the installed build, and remember that an explicit model or the saved model in a resumed session takes precedence over the new-session xAI default.

When should I use direct Tools, Codemode, MCP, Virtual Models, or Durable?

Choose the smallest boundary that solves the problem:

See Use Codemode and MCP, Route Virtual Models, and Build a Durable Agent for the complete boundaries and examples.

Is Pi free?

The Pi source and npm packages use open-source licenses. Model providers may charge for inference, so configure account limits before making API calls.

Reading this book

Should I read the chapters in order?

Read chapters 1 through 3 in order for the project overview, package architecture, and agent loop. Chapters 4 through 11 each focus on one subsystem and can be read independently after that foundation.

Which Pi revision does this documentation describe?

The current documentation baseline is the official Pi 1.0.0 release. The editorial review ledger pins verification to a13d35a742c6ef8462812a28fbe1d8c8b7431c32, reviewed on 2026-10-06. Recheck the upstream source before relying on a version-sensitive API or default.

Why do examples use TypeScript?

Pi is implemented in TypeScript and publishes type declarations with its packages. The examples use TypeScript when types clarify the API. Shell, JSON, and JavaScript appear where they match the runtime or configuration format.

Can I copy the examples into my project?

Yes. Install the package named by the example and match the documented Node.js requirement. Start with the Quickstart for a complete runnable setup.

Contributing

How do I report a translation error?

Open an issue at github.com/pifydev/docs/issues. Include the page path, the sentence, and your proposed correction.

Can I add a page or chapter?

Yes. Submit matching English and Vietnamese files, keep their heading and code-fence structures aligned, and follow CONTRIBUTING.md.

Where is the terminology policy?

The documentation glossary defines canonical terms. Preserve identifiers and translate only the concepts that the glossary marks as translatable.

Common pitfalls

These implementation details are useful when diagnosing provider-specific failures in the current 1.0.0 baseline:

These corrections expose no public API. If an OpenAI-compatible endpoint still rejects an image-only turn, inspect the serialized content parts. For split-turn compaction, the separation prevents the continuation guidance from being treated as earlier conversation; no public compaction option controls it.

Older releases could report a Claude Fable refusal while summarizing a split turn. Treat that as a historical diagnostic comparison, not a current API setting: verify that prior transcript remains under # Conversation and only the continuation guidance appears under # Instructions. The current 1.0.0 behavior keeps those roles separate.

My tool result does not reach the model

An AgentTool.execute implementation returns an AgentToolResult with content and optional details or usage; it does not construct a ToolResultMessage. Agent Core associates the result with the current ToolCall and creates the protocol message with the matching call ID and Tool name. If no result reaches the model, inspect the returned content blocks and the tool_execution_end event.

My session does not resume

The coding agent stores sessions under ~/.pi/agent/sessions/ by default. Confirm the session exists and start Pi from the expected working directory, or pass the session path or ID explicitly.

The TUI behaves oddly over SSH

Increase PI_TUI_ESC_TIMEOUT for a high-latency terminal. See Environment variables.

The provider returns HTTP 429 with a valid key

HTTP 429 indicates rate limiting or exhausted quota, not an invalid key. Check the provider account, wait for the retry window, or select another model.