---
title: First Mission (guided onboarding experience)
---

# First Mission (guided onboarding experience)

## What it is

The **First Mission** is a short, coached experience that runs automatically right after a new user finishes onboarding setup on Windows or macOS. It gives the user's computer a safe, guided tune-up — a read-only health check across performance, security, privacy, drive health, and hardware — then walks them through the worthwhile fixes one at a time, each explained in plain language and approved (or skipped) individually. Personal files are never touched without an explicit, per-item OK, and it finishes with a plain-English before/after report.

It ships on Windows and macOS, and fires at most once per install (when neither `firstMissionCompleted` nor `firstMissionDismissed` is set in the user's Omniscio settings). It does not run on Linux (which has no missions yet), and it does not run again once the user has either completed or dismissed it.

## Where to find it

### When it appears

The First Mission launches immediately after the user clicks **Create Project** in the final step of the onboarding wizard (the **Project** step, where they pick a folder). Instead of opening a blank session, Omniscio opens a real working session: the agent introduces itself and asks one quick yes/no — whether it can run a read-only check of the system — then runs the scan once the user agrees (each system command still goes through the app's normal command-approval flow). It is also the "Tidy my computer" agent the onboarding tour spawns as the user's first real session. The session is otherwise indistinguishable from a regular session — it lives in the sessions sidebar, uses the active Claude account, and can be archived, paused, or otherwise managed like any other session.

If the host platform has no missions (e.g. Linux), or if the mission has already been completed or dismissed, the Project step falls back to a plain blank session exactly as it did before the First Mission feature existed.

**Three ways to reach it.** Besides the automatic launch above, on a host that offers missions (Windows + macOS) the mission is discoverable two other ways so already-onboarded users (and anyone who skipped it) can still find it:

- **Blank-session nudge** — any session that has no messages yet shows a "New here? Let me show you something useful" card with a **Run a guided mission** button (plus a "No thanks, don't show this again" link that sets `firstMissionDismissed`). This nudge appears only while the mission hasn't been completed or dismissed, so it gently prompts once in empty sessions and then stops. It shows only for real folder projects (not virtual projects like Claude, SMS, or Search).
- **"Ready to go" replay** — when a project is selected with no open session, the main-panel empty state offers **Run a guided mission** as a secondary action next to **New Session**. This one stays available (on any host that offers missions) even after the mission is completed or dismissed, so the mission is always replayable.

## How it behaves

### The flow

The mission is a normal conversation with a real working agent (the scripted card
beats were retired 2026-08-11 — the owner wanted a real agent that responds, not a
canned card script):

1. **Ask permission first** — the agent introduces itself in a sentence or two and asks
   one yes/no: may it run a read-only check of the computer? Nothing happens until the
   user agrees; a "no" gets a polite sign-off and a full stop.

2. **Scan quietly** — on a yes, it sets up a safety net first (a Windows System Restore
   point, or verifies Time Machine on Mac), then runs a read-only scan across about a
   dozen areas — disk junk, startup programs, bloatware, updates, power, privacy,
   security, drive health, backups, and account security. The user sees nothing until
   the findings are ready.

3. **Findings, then one fix at a time** — the agent shows a short, plain-language
   overview (one line per area with the key number), then walks through the worthwhile
   fixes individually. Each is explained — what it is, why it matters, what changing it
   does — and the user approves or skips it item by item, never a blanket "do everything."

4. **Safe by default, with undo** — personal files stay off-limits unless approved
   item by item, every change is reversible and recorded, and a decline at any point
   gets one warm sentence and a full stop — never persuasion. It closes with a
   plain-English before/after report.

### Trust model

The mission is designed around explicit consent at every step:

- The **scan** is strictly **read-only**. No files are touched, and the user agrees to it up front.
- A **safety net comes first.** Before any change, the agent creates a System Restore point on Windows (or verifies Time Machine on Mac), so anything can be rolled back.
- **Every change is approved item by item.** Nothing is executed on a blanket "yes," personal folders (Documents, Desktop, Pictures, work folders, etc.) stay off-limits without explicit per-item consent, and each applied fix is reversible and recorded for the final report.

Because the agent runs under the app's normal command approval, every system command is individually visible and approvable — there is no hidden execution path.

### How to replay it

If a user dismissed the mission with "Maybe later" and wants to try it again later, or if they completed it and want to run a fresh mission on a different session, they can replay it from the project empty-state at any time:

1. Select any project in the sidebar that has no active session (the main panel shows a "Ready to go" empty state).
2. On a host that offers missions (Windows + macOS), a **Run a guided mission** button appears as a secondary action next to the usual **New Session** button. It is **always available** there — completing or dismissing the mission never removes it (the mission is never a one-way door).
3. Click it — Omniscio opens a **MissionPickerModal** showing the available missions for the host platform. Selecting a mission from the picker launches a new session with that mission's prompt pre-loaded.

### Platform support

The First Mission ships on **Windows and macOS**. The tune-up runs OS-native, read-only scans and approval-gated fixes written for both platforms (the Windows fix library and the macOS equivalents live in the mission prompt), so it behaves consistently on each. Linux is not yet offered: on a host with no missions the onboarding Project step silently skips the mission and opens a plain blank session exactly as before. The single source of truth for which platforms a mission is offered on is `MISSION_REGISTRY` in `src/shared/missions/registry.ts` (each mission lists `platforms: ['win32', 'darwin']`); UI surfaces gate on `hasMissionsForPlatform(getHostPlatform())`.

### Settings flags

Omniscio tracks the mission state in two boolean settings:

| Setting                 | What it means                                                                                  |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| `firstMissionCompleted` | The mission ran to completion (the tune-up finished, or the user stopped after the findings)  |
| `firstMissionDismissed` | User opted out (declined the mission, or the blank-session nudge's "don't show again" link)   |

Both default to `false`. They gate only the **automatic** mission launch from ProjectStep: when either is `true`, ProjectStep opens a normal blank session instead of the mission. They do **not** affect the manual **Run a guided mission** replay button in the Dashboard empty-state, which stays available on any host with missions so the mission is always replayable.

## For agents

### How it works (for agents with repo access)

The mission session is launched with `source: 'first-mission'` from three call sites:

- **ProjectStep.tsx** (`src/renderer/src/features/onboarding/steps/ProjectStep.tsx`) — auto-launches the mission via `launchSession(projectId, undefined, undefined, undefined, undefined, 'first-mission')` when the host offers missions (`hasMissionsForPlatform(getHostPlatform())`) + not completed + not dismissed (the one-shot automatic launch).
- **SessionPanel.tsx** (`src/renderer/src/features/sessions/SessionPanel.tsx`) — the blank-session empty state (a real-folder project's session with zero messages) renders the "Run a guided mission" nudge on a host with missions while neither flag is set; same `launchSession(..., 'first-mission')` call. This is the most discoverable entry, since it appears wherever a new/unsure user is staring at an empty composer.
- **DashboardDesktopLayout.tsx** (`src/renderer/src/features/dashboard/DashboardDesktopLayout.tsx`) — the selected-project empty-state offers "Run a guided mission" as a **secondary** action gated on the host platform (`hasMissionsForPlatform(getHostPlatform())`, independent of the flags), so replay is always available.

On the backend, `session-create-prompt-assembly.ts` handles mission-sourced sessions: it composes the mission prompt (via `composeMissionPrompt` from `first-mission/mission-prompt.ts`), writes the connection file for `injectInAppToken` missions, and sets `launchPrompt` — so the mission prompt is composed server-side and is never surfaced as a visible operator bubble in the session. The first-mission prompt (`resources/first-mission/mission-prompt.md`) runs its OWN OS-native tune-up and no longer drives the bundled tidy CLI, so the `{{NODE_BIN}}` / `{{CLI_PATH}}` / `{{MANIFEST_DIR}}` placeholders are simply left unsubstituted (harmless — the substitution is a no-op when the template omits them).

The first-mission agent speaks plain prose (its prompt, `resources/first-mission/mission-prompt.md`, emits no `mission:*` fenced blocks). Other missions (e.g. find-local-events, unclaimed-money-check) still emit structured `mission:<kind>` fenced blocks: the shared parser `src/shared/mission-block-parser.ts` detects these; the agent-markdown pipeline renders each as a `MissionCard` from `src/renderer/src/components/ui/mission/MissionCards.tsx`, whose buttons call `useSessionStore.getState().sendResponse(sessionId, text)` — plain natural-language turns — so a malformed block degrades to chat. Mission cards set `pendingAction = 'mission'` in the process manager, flipping the session dot to "Your turn"; the first mission reaches "Your turn" through the normal question/turn detection instead.

## Related

- [first-time-setup.md](first-time-setup.md) — the onboarding wizard that precedes the First Mission
- [question-widget.md](question-widget.md) — the marker-driven card pattern the mission mirrors
- [start-a-new-session.md](start-a-new-session.md) — the normal session launch flow the First Mission extends
- [default-claude-project.md](default-claude-project.md) — the auto-created `~/Claude` project where replay missions often run