Configuration

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.

Let's work on the "Configuration" lesson from Pi School.

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. Once this is set, new sessions use it automatically — no need to pick a model every time.

A note on themes

You might expect a theme setting here too, but we’re leaving it unset on purpose. Pi checks your terminal’s background color the first time it runs and picks "dark" or "light" for you automatically. There’s no "auto" value that continuously follows your system’s light/dark setting — it’s a one-time detection at first run. If you want to override it later, set "theme": "dark" or "theme": "light" explicitly, or run /settings inside Pi to pick one interactively.

Restart to apply changes

Settings are read at startup. Restart pi, or run /reload inside an existing session, to pick up changes.

Let's check that the "Configuration" lesson is complete.