Pi reads a global settings file at startup that applies to every session, in every project, on your machine. In this lesson you’ll create one and set a default model so you don’t have to pick one every time you start Pi.
Where settings live
- Global —
~/.pi/agent/settings.json. Applies everywhere. - Project —
.pi/settings.json, inside a specific project. Overrides global settings for that project only. Nested objects merge; the project’s values win where they conflict.
We’re creating the global one in this lesson.
Set a default model
{
"defaultProvider": "openrouter",
"defaultModel": "google/gemma-4-31b-it:free"
}Swap in whatever provider and model you connected to in the Installation lesson (for Sign in with ChatGPT, the provider is openai). Once this is set, new sessions use it automatically, no need to pick a model every time.
Picking a model with /model only changes the current session. Press Ctrl+S in the /model picker to save your choice as the default instead.
A note on themes
You might expect a theme setting here too, but we’re leaving it unset on purpose. The default theme, "system", takes its colors from your terminal’s own palette and follows it live, so if your terminal switches between light and dark, Pi switches with it. If you want something else, run /settings inside Pi to pick a theme interactively.
A note on fullscreen
Pi runs fullscreen by default: it keeps its own scrollable transcript, with the editor pinned at the bottom. You can select text with the mouse and search the transcript with Ctrl+Shift+F (Ctrl+F on Windows). If you’d rather keep your terminal’s normal scrollback, set "tuiMode": "regular".
Restart to apply changes
Settings are read at startup. Restart pi, or run /reload inside an existing session, to pick up changes.