Onboarding & First Run
Relevant source files
The following files were used as context for generating this wiki page:
The Onboarding and First Run system in QQcode is a guided initialization process designed to set up the environment for a new user. It ensures that essential configurations, such as API keys and UI themes, are established before the core coding assistant becomes operational. The system is triggered automatically when the application detects a missing configuration file or an absent API key during startup.
This module provides a Textual-based terminal user interface (TUI) that walks the user through a series of screens to collect provider information, authenticate via API keys or OAuth, and customize the visual experience. Upon completion, the system persists these settings to the user's home directory (typically ~/.qqcode/), allowing subsequent runs to bypass the setup and enter the interactive chat directly.
Sources: vibe/cli/entrypoint.py:126-130, vibe/setup/onboarding/screens/api_key.py:100-110
Startup Logic and Triggering
The entrypoint of the application manages the transition into the onboarding flow. Onboarding is triggered in two primary scenarios:
- Manual Setup: The user explicitly runs
qqcode --setup. - Automatic Detection: During the configuration loading phase, if a
MissingAPIKeyErroris raised, the application catches the exception and invokesrun_onboarding().
The application checks for the existence of the config.toml, instructions.md, and qqcodehistory files in the global configuration directory. If they do not exist, default versions are created.
Sources: vibe/cli/entrypoint.py:120-135, vibe/cli/entrypoint.py:143-165
Onboarding UI Architecture
The onboarding process is structured as a series of screens managed by a central application. Each screen inherits from OnboardingScreen and defines its own keyboard bindings and transition logic to the NEXT_SCREEN.
Screen Transition Flow
The flow is linear, guiding the user from a welcome message to theme selection, and finally to provider configuration.
Core Components
| Component | Description | File Reference |
|---|---|---|
WelcomeScreen | Displays a typing animation and branding message. | vibe/setup/onboarding/screens/welcome.py |
ThemeSelectionScreen | Allows users to cycle through built-in Textual themes with a live preview. | vibe/setup/onboarding/screens/theme_selection.py |
ApiKeyScreen | Handles provider selection, API key entry, and OAuth authentication. | vibe/setup/onboarding/screens/api_key.py |
OnboardingApp | The main Textual app container for the onboarding screens. | tests/onboarding/test_ui_onboarding.py:47 |
Detailed Screen Logic
Theme Selection and Customization
The ThemeSelectionScreen provides a carousel of BUILTIN_THEMES. It includes a PREVIEW_MARKDOWN block to show how code, headings, and tables will appear in the selected theme.
- Navigation: Uses
UpandDownkeys to updateself.app.theme. - Persistence: On
action_next, it callsVibeConfig.save_updates({"textual_theme": theme})to persist the choice to the TOML configuration.
Sources: vibe/setup/onboarding/screens/theme_selection.py:49-110
Provider Configuration and Authentication
The ApiKeyScreen is the most complex part of the onboarding flow, supporting three distinct authentication paths:
- API Key Path: For providers like Mistral, OpenRouter, or Z.ai, the user enters a string which is saved to the
.envfile viaset_key. - OAuth Path: For Anthropic (subscription) or Qwen, the system triggers a browser-based authentication flow using PKCE.
- Local Path: For
llamacpp, no key is required, and the system simply verifies the local server (defaulting to port 8080).
Data Persistence
The onboarding system interacts with two primary storage files located in ~/.qqcode/:
1. config.toml
Stores UI preferences and active model selections.
- Method:
VibeConfig.save_updates(updates) - Key Fields:
textual_theme,active_model.
Sources: vibe/core/config.py:470-495, vibe/setup/onboarding/screens/theme_selection.py:112
2. .env
Stores sensitive credentials. Environment variables in this file take precedence during startup.
- Method:
set_key(GLOBAL_ENV_FILE, env_key, api_key) - Common Keys:
MISTRAL_API_KEY,OPENROUTER_API_KEY,ANTHROPIC_API_KEY.
Sources: vibe/setup/onboarding/screens/api_key.py:65-68, vibe/core/config.py:38-45
Summary
The Onboarding & First Run system provides a seamless bridge between installation and usage. By abstracting the complexities of configuration file management and multi-provider authentication (API keys and OAuth) into a guided TUI, it ensures that users are correctly configured with their preferred visual theme and necessary credentials. The system's tight integration with the application entrypoint ensures a robust "zero-config" start experience for new developers.
Sources: vibe/cli/entrypoint.py:130-140, tests/onboarding/test_ui_onboarding.py:75-90