First-time setup

What it is

The first-time setup is the flow that takes a freshly installed Omniscio from "the app just opened for the first time" to "I have a working session running against my own code." It is Setup v2, the cinematic full-bleed onboarding the team calls the Cinematic Cascade — the one canonical first-run experience, stepped through on a numbered rail. Plus a few opinionated startup defaults, it makes this almost-zero-touch — most users answer a handful of questions, connect an account, and land in a working dashboard with a default project already created.

The cascade is a rail of numbered steps, not two phases: Language and look, Tell us about you, How your data is handled, Choose your AI, Connect your AI, Add an API key (optional), Install the essentials, Grant permissions, Choose agent autonomy, Share your feedback, and What happens next — followed by the All-set completion beat. That is 11 steps on macOS and 10 everywhere else — the permissions step is a macOS-only grant (microphone and accessibility) and is dropped entirely, not merely greyed out, on Windows and Linux.

Behind the scenes Omniscio also auto-creates the Claude project at ~/Claude so general-purpose chats have a home from minute one, and a default "Omniscio" sidebar group seeds the built-in virtual projects (Recipes, Skills, CLI Tools, Cron Jobs, etc.) so they're grouped instead of cluttering the top of your project list. When the cascade finishes it drops you in the Inbox, where two pinned welcome cards head the list above the starter agents it has already prepared.

The cascade installs CLI tools only — it never installs, probes or mentions the Claude Code extensions. Both of those are now optional: Playwright MCP became a bundled, composed per-session built-in, and the Superpowers plugin was superseded by Omniscio's own built-in Dev Pipeline. The post-onboarding extensions banner still exists (it lists genuinely-required missing extensions) but is currently quiet, because no extension is required any more. Both are still listed under Settings → Extensions if you want to install one by hand. See mandatory-claude-extensions.md for the full story.

Where to find it

How to use it

1. Launch Omniscio for the first time. Setup v2 opens automatically over an opaque cover, so the app never flashes its empty shell behind it. The rail on the left numbers every step, and the first is Language and look — pick your language and the look you want, and the live preview updates as you click. The rail is the map: Setup · N of M tells you where you are, and arrows move between steps.

2. Tell us about you. A short, human step — what you do, and how you heard about Omniscio. It is there so the app can greet you in its own voice on the next screen rather than in a generic one; skip it if you would rather not say.

3. How your data is handled. Three plain statements about where your conversations live and who can see them, shown before you connect anything — your data stays between you and your AI provider, it stays on your computer, and Omniscio has no access to your conversations.

4. Choose your AI. Pick the AI tool your agents will run on. Claude is the default and the headline path; if you use a different tool, the step offers it — and if you are not sure, it will set you up with Claude, which is the right answer for almost everyone.

5. Connect your AI. Click the connect action and Omniscio opens your default browser to Anthropic's OAuth consent page; sign in to Claude.ai, click Authorize, and the step advances by itself when the local callback succeeds. A green checkmark and your email confirm Account connected. On a build without the managed sign-in pool, the step instead offers Sign in with your Claude account, which opens a real Terminal window running the Claude CLI's own login — the step tells you that before you click, so the plain text window reads as expected rather than as something breaking. On Linux, where Omniscio cannot open that window for you, the step shows the single command to run (claude auth login) instead of flashing an error. If an account already exists (Omniscio auto-imports the Claude CLI's credentials at boot, and re-runs keep your accounts), the step opens directly in a "Using your API key account" / connected state with Continue as the primary action and a secondary "Use a different account" button — you are never asked to sign in twice. This step is skippable; you can add an account later from Settings → Accounts. See add-a-claude-account.md for the full account model (login vs API key, multiple accounts, the rate-limit-tier-aware account pool).

6. (Optional) Add an API key. A paste field for a raw sk-ant-... Anthropic API key, and the step says outright that you can explore right away without one. The key is optional — it unlocks extras like AI-generated session titles and summaries and is not needed to run your agents. Most users skip it; an API key is metered per-token and is mainly useful as a fallback for AI features when you do not have a Claude.ai subscription, or to run sessions when your subscription accounts are exhausted. Omniscio stores the key encrypted via safeStorage. By default, API key accounts power AI features only — to allow them to spawn sessions, flip the Allow API Keys to Run Sessions toggle in Settings → Accounts.

7. Install the essentials. Omniscio probes your machine and installs the bare minimum: the two required CLI tools — Claude Code ("the engine your agents run on") and Git — plus browser automation, shown in the same list with its status live (starting…, installing…, done). Everything else installs on demand later. Sign-in is deliberately not installed here — the Connect step already owns your account. The first two rows gate the Continue button; browser automation is non-blocking (it is a large download, and saved Browser Logins use your own Chrome), so a slow or failed install never traps you in first-run. Anything not installed here can be added later from Settings → Connected Tools.

8. Grant permissions (macOS only). On a Mac, this step asks for the two grants voice and hotkeys need — Microphone (voice dictation) and Accessibility — and explains what each is for. On Windows and Linux there is nothing to grant, so this step does not appear at all and the rail counts 10 steps instead of 11.

9. Choose agent autonomy. Pick how much an agent may do before Omniscio stops to ask: Read-only, Guarded (the recommended default — auto-approves edits inside the project, asks for commands and outside-project writes), Autonomous, or Full trust. You can change this any time under Settings → Workflow; see agent-permission-level.md.

10. Share your feedback. How to report bugs when something breaks or looks off, and how to suggest improvements — it is a beta, and this step is where the app asks you to say so rather than wait for you to find a menu.

11. What happens next. A short demo of what you are about to see, and the promise of the step after it: your agents start working. Completing the cascade takes you to the All-set beat, then lands you in the Inbox — where two pinned welcome cards ("Welcome to Omniscio!" and the free-starter-agents explainer) head the list, with the starter agents Omniscio has already prepared sitting directly beneath them. Those starter missions are prepared and waiting on your reply, not already running, so the first message costs nothing until you send it.

12. (After onboarding) The extensions banner stays quiet for now. Omniscio has a launch-time amber banner for missing required Claude Code extensions — but no extension is required any more (Playwright MCP became a bundled per-session built-in; Superpowers was superseded by the built-in Dev Pipeline), so you should not see it. If one ever does appear, click Install or Later to snooze it for 24 hours. See mandatory-claude-extensions.md.

13. Open Settings to fine-tune anything. The gear icon in the toolbar (or the Settings virtual project in the Omniscio sidebar group) opens the full settings modal. Common first-day adjustments: notification sounds and silence schedule (notifications-and-silence.md), keyboard shortcuts, the Default Projects Folder for Quick Create projects, the Allow API Keys to Run Sessions toggle, and the MemPalace persistent memory toggle. See settings-virtual-project.md for the alternate sidebar entry to Settings.

What if Google Auth is required at your install? Omniscio has an optional Google sign-in gate behind the requireGoogleAuth feature flag. The default is false — most users never see it. When enabled and Firebase is configured, the wizard prompts for a Google sign-in before the Account step; when enabled but Firebase is missing it falls through silently so users are never locked out of their own app.

How it behaves

The starter agents — and their spend cap

Finishing setup also starts a few starter agents for you: the guided missions from the Onboarding Hub, pre-spawned in the background so you come back to work already in progress rather than an empty dashboard. They run on Omniscio's own company-funded model lane — not your Claude account and not your API key — and they are parked waiting on your first reply rather than spending on their own initiative.

That lane is capped, so a starter agent can never run away with company spend:

Cap	Amount	What it means
Per starter session	$0.50	A single starter agent stops once it has spent $0.50.
Per person, across all of them	$1.00	The starter agents together stop at $1.00 for a given account.

The per-session cap is the one that normally bites. A starter agent that hits a cap simply stops — nothing is billed beyond it, and nothing is charged to you at any point. So if one of your first agents goes quiet partway through a task, the budget is the usual reason.

This affects only the pre-spawned onboarding agents. A session you start yourself, and any agent you launch normally, runs on your own account and is never touched by this cap. You can switch the pre-spawn off entirely with Settings → Lab → "Pre-spawn onboarding missions on the company DeepSeek route", and the suggest-only mission prompt remains as the fallback.

How it works

The cascade is mounted globally by src/renderer/src/features/onboarding/setup-v2/SetupV2Mount.tsx, which renders nothing at all on an idle, already-onboarded app — it shows an opaque first-run cover while a first-run is pending and then lazily loads src/renderer/src/features/onboarding/setup-v2/SetupV2Shell.tsx. The step order lives in src/renderer/src/features/onboarding/setup-v2/setup-v2-nav.ts, which exports SETUP_V2_FRAME_IDS and the platform-filtered SETUP_V2_VISIBLE_FRAME_IDS (the permissions frame is dropped on Windows and Linux), and derives every rail label and the "Setup · N of M" eyebrow from that list — so the numbering can never drift from what is actually shown. Each step is a lazy-loaded component in src/renderer/src/features/onboarding/setup-v2/frames/ (PreferencesFrame, AboutYouFrame, PrivacyFrame, PreferredHarnessFrame, SignInFrame, ApiKeyFrame, InstallFrame, PermissionsFrame, AutonomyFrame, BetaFeedbackFrame, PreLaunchDemoFrame). A frame that throws degrades to a skippable recovery card rather than crashing the whole first-run.

The Connect your AI step invokes IPC.ACCOUNT_ADD_LOGIN, which routes to authService.login() in src/main/services/auth/auth-service.ts — the PKCE OAuth flow opens the browser, captures the redirect, exchanges the code for a refresh token, and writes an encrypted account row into config.json. The Add an API key step calls IPC.ACCOUNT_ADD_APIKEY with name: 'API Key' and the trimmed key, which validates against the rate-limits endpoint before persisting. The shared usability predicate src/shared/account-usability.ts is also what lets the main-process checkClaudeLogin probe treat an Omniscio-managed account as a satisfied "Claude Code Login" — in-app OAuth never writes the CLI's own ~/.claude/.credentials.json, but spawned CLIs authenticate from env credentials anyway.

Where you land at the end is decided by src/renderer/src/features/onboarding/setup-v2/post-onboarding-landing.ts: always the Inbox, with a completion toast chosen by whether any starter agents are waiting for you. There is deliberately no project step in the cascade — you add projects afterwards from the + at the top of the projects sidebar, and the auto-created ~/Claude project is already there if you want to chat without setting one up. See add-a-project.md.

The auto-created ~/Claude project is seeded by ensureClaudeProject() in src/main/services/claude-project.ts, called from src/main/index.ts at app startup right after the database is ready. The default "Omniscio" sidebar group that holds the built-in virtual projects (Recipes, Skills, CLI Tools, Cron Jobs, Session Search, Automations, Quick Replies, AI Coaching, PRDStack) is seeded by a fresh-install migration — see projects-sidebar.md. The mandatory-extensions probe runs on first startup and on every subsequent startup (gated by settings.onboardingCompleted so it doesn't double-prompt during the wizard) — see mandatory-claude-extensions.md. The Google Auth gate sits in front of the wizard entirely and is documented in docs/plans/2026-04-16-google-auth-gate-design.md.

Related

• add-a-claude-account.md — what an account is (login vs API key), how to add more later, the active-account model
• add-a-project.md — the full Add Project dialog after onboarding (Quick Create, Browse Existing, GitHub clone)
• start-a-new-session.md — once you have a project, spawning and running sessions in it
• mandatory-claude-extensions.md — Playwright MCP + Superpowers auto-install during onboarding, banner for existing users
• default-claude-project.md — the auto-created ~/Claude project that's there before you add anything
• projects-sidebar.md — the default "Omniscio" group that holds the built-in virtual projects
• inbox-overview.md — once sessions are running, the Inbox is your daily triage view