Pi Agent Configuration Explained

Pi Agent uses JSON-format configuration files, supporting both global configuration and project-level configuration.

Configuration File Location

Pi Agent reads configuration from two fixed paths, and the two have different priorities.

You can directly edit the JSON file, or use the interactive mode's/settingscommand to modify common options.

Model and Reasoning Configuration

The following configuration items control which provider and model are used by default, and how the reasoning budget is allocated.

Custom reasoning budget example:

It should be noted that the values below are for demonstration purposes only, not official defaults.

The meaning of each level and its corresponding example budget is as follows:

UI and Display Configuration

The following configuration items control theme appearance, editor layout, and startup behavior.

Recommended external editor configuration for VS Code users:

--waitThe parameter ensures that Pi Agent resumes only after VS Code closes the file; otherwise Pi Agent continues executing immediately after the editor opens.

Network Configuration

The following configuration items control the proxy Pi Agent uses when accessing model APIs.

Setting up a proxy (for environments such as mainland China where a proxy is needed to access APIs):

Context Compression Configuration

When the context approaches its limit, Pi Agent automatically compresses historical messages. These settings control when compression is triggered and what is retained.

Retry Configuration

The following configuration items determine automatic retry behavior after request failures, including the number of retries and the backoff interval.

It is recommended to keepretry.provider.maxRetriesit at 0, unless you truly need provider-level retries.

Setting it to greater than 0 may cause SDK-level retries to block Pi Agent when usage limits are exceeded, rather than letting Pi Agent's retry mechanism handle it.

Message Delivery Configuration

The following configuration items control when and how messages you insert in the conversation are sent to the model.

Terminal and Image Configuration

The following configuration items control how images are displayed in the terminal and how they are processed before being sent to the model.

Shell Configuration

The following configuration items control the shell and command prefix used when Pi Agent executes bash commands.

Example of using tools such as mise or asdf to manage the Node.js version:

Model Cycling Configuration

The following configuration items control which models can be seen when cycling through models with Ctrl+P.

Configuration Merge Rules

Project configuration (.pi/settings.json) overrides global configuration (~/.pi/agent/settings.json).

Nested objects usemergerather than replacement. The following example illustrates this.

Global configuration file ~/.pi/agent/settings.json:

Project configuration file .pi/settings.json:

In the effective configuration after merging, theme takes the global dark, compaction.enabled takes the global true, and compaction.reserveTokens is overridden to 8192 by the project configuration.

In other words, the project configuration only overrides the fields it explicitly declares, and all other fields continue to use the global configuration.

Complete Configuration Example

The following is a typical global configuration file:

warnings.anthropicExtraUsage is a boolean, defaulting to true.

It provides a reminder when Anthropic subscription authentication may incur additional paid usage.

packages is an installed package filter configuration, used to declare which packages to load.