All RFCs
RFC 0044
Discussion

First Time Setup

Visibility Public
pi
Authors
Armin Ronacher
Created
June 9, 2026
Updated
June 9, 2026

Introduce an experimental first-time setup flow, for now gated behind PI_EXPERIMENTAL=1, for users starting Pi with the default agent directory until we like it. The setup should detect the system appearance, offer an explicit dark or light theme choice, and ask whether the user wants to opt into analytics data sharing as described in RFC 0038.

Problem

Today Pi relies on defaults during first launch, but theme detection is not always correct. A first-time setup gives users a chance to correct the detected theme before they start using the product. It also gives us a clear place to ask for analytics consent instead of silently relying on defaults or adding the prompt later in an unrelated flow.

Proposal

When PI_EXPERIMENTAL=1 is set and the agent directory is the default one, Pi should show a first-time setup dialog if setup has not already been submitted. The dialog should preselect the detected system theme but allow the user to choose either dark or light explicitly. It should also offer analytics data sharing as a true opt-in choice (thus no defaulting to on or off), with concise text explaining that opting in stores a tracking identifier in settings.json and enables the analytics behavior described in RFC 0038.

Persistence and Scope

Submitting the dialog should write settings.json, along with the selected theme and analytics preference. The presence or absence of settings.json is the completion marker. Declining analytics should still count as completing setup, so the user is not asked again. The setup should not appear when Pi is using a custom agent directory, because those environments are more likely to be scripted, isolated, or intentionally configured.

Open Questions

  • We may also expose the same setup flow manually through /setup, but this should be decided after trying the first-run experience. For now, the flow should remain experimental until we are happy with the UX and confident it belongs in the default product.
  • What is needed to graduate that feature for all users?
  • Do we want to ask for opt-in analytics even prior to having analytics code in place or defer this until later?