--- title: First-time setup --- # 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](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](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](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](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](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](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](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](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](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](../plans/2026-04-16-google-auth-gate-design.md). ## Related - [add-a-claude-account.md](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](add-a-project.md) — the full Add Project dialog after onboarding (Quick Create, Browse Existing, GitHub clone) - [start-a-new-session.md](start-a-new-session.md) — once you have a project, spawning and running sessions in it - [mandatory-claude-extensions.md](mandatory-claude-extensions.md) — Playwright MCP + Superpowers auto-install during onboarding, banner for existing users - [default-claude-project.md](default-claude-project.md) — the auto-created `~/Claude` project that's there before you add anything - [projects-sidebar.md](projects-sidebar.md) — the default "Omniscio" group that holds the built-in virtual projects - [inbox-overview.md](inbox-overview.md) — once sessions are running, the Inbox is your daily triage view