SaveMyToken logoSaveMyToken.
← All agent setup guides

CONFIGURATION, EXPLAINED

Pi Coding Agent Config: Settings, Models & API Setup

Read Pi settings, third-party models, sampling controls and MCP in one continuous window. Select a setting for its explanation.

Official sources reviewed 2026-10-08One config · select a setting to read its explanation
~/.pi/agent/settings.json

One continuous config. Click a line for its explanation. Commented lines show optional settings, alternatives or separate setup; the copy button includes active settings only.

JSON CONFIGSections are marked inside the codeSELECTED SETTINGOnly what you click is explained here
{

Model & responses

Choose the model provider

defaultProvider

Selects the startup provider registered in Pi's catalog.

In the main config~/.pi/agent/settings.json
In this example
"anthropic" is the example value; it is not a universal recommendation.
If you leave it unset
Omission leaves this choice to the installed version, provider and higher-priority configuration.
When to change it
Use the exact provider ID from /model.
What changes / what to watch
Authentication and provider selection are separate; an unavailable credential hides models.
Check that it worked
Reload the intended file or start a fresh session. Inspect the active model, tools or setting, then check one small task before relying on the change.
Official reference ↗

Copy keeps the parent structure. Merge it into the file shown above.

},
},
}
},
}
// ── Connection alternatives & separate-file setup ──
// ~/.pi/agent/models.json
// {
// "providers": {
// "example": {
// "models": [
// {
// "samplingParams": {
// }
// }
// ]
// }
// }
// }
// ~/.pi/agent/mcp.json
// {
// "mcpServers": {
// "docs": {
// }
// }
// }
Model & responses · defaultProvider

Find an explained key & its source

SETTINGS AND OFFICIAL SOURCES

Explained settings index

This index covers the settings explained in this handbook. Follow the official sources for the complete schema, additional plugins and platform-specific options. The index is not a file to paste, and not every key is available in every client or scope.

39 of 39 documented entries · showing 30

Setup, troubleshooting & official sources

Where settings take effect

Pi Coding Agent, upstream revision 6b07b4e57269. This is not the Pi conversational assistant. Native files have different purposes and are marked in the reader.

  1. Personal settings live in ~/.pi/agent/settings.json; trusted .pi/settings.json supplies project preferences. PI_CODING_AGENT_DIR can move the personal directory.
  2. Run /login for an included provider or supply its API-key environment variable. Choose /model and /thinking; a resumed session can keep its own saved choices.
  3. Use /reload for edited settings and resources. Open /model to reload models.json. Keep auth.json private.

OFFICIAL AND THIRD-PARTY ACCESS

Choose how the agent connects.

Use one model-provider route per session. MCP connects tools and data; it does not replace model authentication.

Built-in providers

Pi's installed and refreshed provider catalog.

Authentication
/login or the provider's environment variable.
Verify
Select an available model in /model.
Open annotated setup →

Third-party or local endpoint

Compatible adapter in models.json.

Authentication
Environment interpolation or another documented credential mechanism.
Verify
Verify API protocol, model ID and tool-call support.
Open annotated setup →

MCP tools

A separate mcp.json connects tools.

Authentication
The MCP server's own authentication.
Verify
Inspect the server and tool list.
Open annotated setup →

AFTER YOU EDIT

Check the effective settings.

  1. Validate settings.json, models.json and mcp.json separately; do not merge their roots into one file.
  2. Check /model, /thinking and /session in a fresh session, including the actual credential route.
  3. Verify custom capacity and sampling declarations against the upstream service.

Documentation-based examples. No live model calls or measured cost savings are claimed.

COMMON QUESTIONS

A few useful distinctions.

Can I put everything in settings.json?

No. Preferences, model definitions, MCP and saved credentials have different files. The reading window keeps them together visually while preserving their real locations.

Does an empty extensions or skills list turn everything off?

No. Those arrays add resources; discovery and built-in extensions have their own disable mechanisms.

Official sources

Checked 2026-10-08. Follow the documentation for your installed version and selected model.

Back to the Pi profile →