Skip to content

feat(onboarding): add the desktop onboarding flow (first-run) - #5996

Closed
ronishrohan wants to merge 15 commits into
mainfrom
codex/reopen-onboarding
Closed

ronishrohan wants to merge 15 commits into
mainfrom
codex/reopen-onboarding

Conversation

@ronishrohan

@ronishrohan ronishrohan commented Sep 28, 2026 •

Copy link
Copy Markdown
Collaborator

Code changes: +4667 -111
Tests: +2381 -31
Others: +1080 -8 (2 binary assets)

Reopens the reverted onboarding feature from #5566 on a new branch.

Includes the combined worker/orchestrator selection step, current cloud provider-connection handling, and focused frontend verification.

Preserves workspace registration and refreshes agent readiness after manual sign-in. Hardens GitHub device login for older CLI versions, reloads, cancellation, timeouts, and rejected credentials.

Adds a real-daemon OAuth matrix for gh 2.4.0, 2.20.2, 2.50.0, and 2.100.0, plus connected production-renderer tests. GitHub OAuth/API responses use an isolated local fixture with disposable credentials; no personal account or keychain is used.

Preserves native quit confirmation on onboarding and during the project handoff after syncing with main. Adds regression coverage for existing-profile onboarding entry rules.

Detects GitHub CLI versions below 2.4.0 and offers Update in onboarding and the in-app GitHub notice. Uses Homebrew or WinGet upgrades, provides manual Linux instructions, and rechecks the resolved version before starting sign-in. Covers failed updates and older copies still on PATH.

Existing cloud accounts and saved remote hosts now bypass first-run onboarding, including delayed profile reads and offline hosts. Failed profile reads leave the app available instead of forcing setup. Local project and completion-marker behavior is preserved.

@github-actions

Copy link
Copy Markdown
Contributor

🏆 Review leaderboard

Sep 21–28, 2026 · UTC

Rank Reviewer PRs reviewed Review rounds PR comments
🥇 @codebanditssss @codebanditssss 38 49 56
🥈 @illegalcall @illegalcall 33 57 6
🥉 @nikhilachale @nikhilachale 17 44 3
4 @ronishrohan @ronishrohan 17 23 8
5 @Rishet11 @Rishet11 12 26 7
6 @mohakchakraborty2004 @mohakchakraborty2004 10 10 5
7 @Prasad-D-Ware @Prasad-D-Ware 9 14 2
8 @Vaibhaav-Tiwari @Vaibhaav-Tiwari 7 9 4
9 @Annieeeee11 @Annieeeee11 6 16 4
10 @harshitsinghbhandari @harshitsinghbhandari 4 4 0

Ranked by distinct external PRs reviewed, then review rounds, then PR comments. Self-activity and bot activity are excluded.

Show 7 more reviewers
Rank Reviewer PRs reviewed Review rounds PR comments
11 @neversettle17-101 @neversettle17-101 3 4 4
12 @Pritom14 @Pritom14 3 3 2
13 @Pulkit7070 @Pulkit7070 3 3 1
14 @Ayash-Bera @Ayash-Bera 2 2 0
15 @ApexYash11 @ApexYash11 1 2 3
16 @somewherelostt @somewherelostt 1 1 2
17 @LaibaFirdouse @LaibaFirdouse 1 1 0

@ronishrohan

Copy link
Copy Markdown
Collaborator Author

#5566

^ old pr, merged by mistake

@OrcInc OrcInc added comp/desktop Electron main process and React renderer. enhancement New feature or request labels Sep 28, 2026
@OrcInc OrcInc added this to the Desktop & UI milestone Sep 28, 2026

@neversettle17-101 neversettle17-101 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two suggestions on the onboarding flow:

  1. Cloud step should be enterprise-only. The "Run sessions in the cloud" step should only appear for enterprise users. Everyone else should default to local and skip the step, so the flow goes GitHub -> project.

  2. Single agent harness picker. Replace the separate orchestrator and worker dropdowns with one agent harness selection. A first-time user is unlikely to understand the orchestrator vs worker distinction during onboarding. The chosen harness can be applied to both roles, and users can split them later in Settings.

@ronishrohan

Copy link
Copy Markdown
Collaborator Author

Cloud step should be enterprise-only. Everyone else should default to local and skip the step.

Replace the separate orchestrator and worker dropdowns with one agent harness selection.

Addressed in 56ea5682: cloud is now disabled by default and the cloud onboarding screen is skipped, so the flow proceeds from GitHub to project setup. Onboarding now uses one agent picker and applies that harness to both roles; users can install another harness from the picker and change role-specific settings later.

@neversettle17-101

neversettle17-101 commented Oct 1, 2026 •

Copy link
Copy Markdown
Collaborator

I was running this locally and found few areas to be worked up on

  1. We want to reduce the number of clicks the user needs to make to get onboarded. we are having 2 onboarding walkthrough - let us keep it at 1 or 0 till we have a walkthrough that highlights the overview of the product
  2. nit: on right click during onboarding we should show limited options and only the once applicable
Screenshot 2026-09-30 at 9 31 00 PM 3. While user is being logged into github we should show a loader. For me once I logged in through the browser it showed me a stale state which led me to believe that I didn't complete the step. 4. We should remove the blurred text of github is connected to make the user understand they can move to the next step Screenshot 2026-09-30 at 9 36 49 PM

@ronishrohan

Copy link
Copy Markdown
Collaborator Author

We want to reduce the number of clicks the user needs to make to get onboarded… on right click during onboarding we should show limited options… While user is being logged into github we should show a loader… remove the blurred text of github is connected

Addressed in 70dc8e9e:

  • Reduced onboarding to one product walkthrough before setup
  • Limited onboarding auth-terminal context menus to applicable basic actions and hid unavailable actions
  • Kept a loader visible while GitHub browser sign-in is active and added a short post-exit reconciliation window so freshly written credentials are detected without a stale retry state
  • Replaced the disabled-looking connected row with a readable status that directs the user to continue to project selection

Also merged the latest main into the branch and resolved the conflicts. Local verification: TypeScript passes; renderer suite passes (359 files, 5,714 tests; 7 skipped).

@neversettle17-101 neversettle17-101 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two review findings:

  1. A failed agent refresh blocks re-probing for 5 minutes (frontend/src/renderer/hooks/useAgentsQuery.ts:24, medium). refreshAgentsIfStale sets its 5-minute throttle timestamp before the request runs and never resets it on failure. If the refresh fails while the daemon is still booting, a newly installed or signed-in harness can stay unselectable for 5 minutes. Suggest setting the timestamp only after a successful probe, or clearing it in the failure path.

  2. Weaker ownership guard on Windows (backend/internal/service/agent/codex_secure_fs_windows.go:449, low). protectCodexPrivateFile now accepts a file owned by any trusted principal and takes ownership of it. The previous check required the current user as owner, so the "changed before ACL protection" guard is weaker. Worth confirming that is intended, and if so, that a test covers a file owned by another trusted principal.

@neversettle17-101 neversettle17-101 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review findings, medium severity (read from the diff; tests not run).

1. A failed onboarding finish can re-run later — _shell.tsx#L1111-L1127

On failure the finish request is intentionally kept in the store so the user can retry, but it is never cleared, and handledOnboardingFinishNonceRef starts at 0 on every ShellLayout mount. If the user leaves onboarding and the shell remounts (for example by navigating to /), the stale request runs createProject again without being asked, behind the "Starting orchestrator" screen. If the first attempt partly succeeded, this can create a duplicate project or orchestrator. Suggest clearing the request when navigating back to /onboarding and having the retry raise a fresh one.

2. Windows credential-file protection accepts any trusted owner — codex_secure_fs_windows.go#L430-L465, #L387-L405

protectCodexPrivateFile used to require the current user as owner. It now accepts any trusted principal (Administrators, SYSTEM) and then takes ownership. The stable-identity and ACL-safe checks remain, and the comment explains the elevated/CI case, but these files hold credentials, so please confirm this relaxation is intended and have a Windows reviewer look at it.

Related: ensurePrivateDirectory decides whether a directory is "new" with an Lstat (L626) before MkdirAll (L630). A process that creates the directory in between gets the lenient "new directory" path. It still needs a trusted owner and a safe ACL, so the window is narrow.

@OrcInc

OrcInc commented Oct 8, 2026

Copy link
Copy Markdown
Collaborator

From the NotesBot call on 2026-10-07, this existing pr appears to be relevant.
Match confidence: 0.62 (fuzzy).

Relevant discussion excerpts:

  • [1:24:13] ronish: Aditya said that she'll help me get my onboarding thing merged today... I think there's some change that we have to make for that.
  • [1:24:48] prateek: Oh, guided onboarding. Nice. You should definitely demo it.

Source thread: https://discord.com/channels/1476302178913357958/1557455414784692224/1557455414784692224

Generated by AO Bot based on the transcript from NotesBot.

@ronishrohan
ronishrohan force-pushed the codex/reopen-onboarding branch from 7fadfda to 7185f73 Compare October 16, 2026 21:12
@MohamedKamran

Copy link
Copy Markdown
Collaborator

Fix: GitHub sign-in loader never finished (6ecbdeb)

Symptom: on the onboarding GitHub step, clicking Sign in with GitHub showed a loader that never resolved.

Cause: the daemon runs gh auth login --web without a terminal and reads the one-time code from gh's output. It only matched gh's older wording:

! First copy your one-time code: ABCD-1234

gh 2.102.0 copies the code to the clipboard itself and prints this instead:

! One-time code (5D0D-70F8) copied to clipboard

The code was never found, so the attempt stayed in starting until the 15-minute timeout and the UI kept showing its loader.

What changed (backend/internal/service/systemcheck/github_device.go), so parsing no longer depends on gh's wording:

  • Code: the first XXXX-XXXX token (uppercase letters and digits). Tokens inside a link are skipped, and the first code found is kept.
  • Verification URL: the first https:// link gh prints, before or after the code. The line no longer needs to contain "URL"; https://github.com/login/device is still the fallback.
  • Color codes: ANSI escapes are stripped before matching. With CLICOLOR_FORCE=1 set, gh wraps the code in color escapes and it was never found.

Verification:

  • New tests in github_device_test.go: gh 2.102 clipboard wording, unfamiliar wording with decoy code-shaped tokens, and colored output with CRLF line endings. The existing old-wording test still passes; all 7 device sign-in tests pass.
  • Ran real gh 2.102.0 through the parser, with and without CLICOLOR_FORCE=1. Both returned the code and the GitHub URL.

Known gap (not in this commit): if gh never prints a recognizable code (a future code format, or gh stalling), the step still waits out the 15-minute timeout. A follow-up could fail the attempt after the existing 10-second code wait and show "Try again" with gh's last output line.

ronishrohan and others added 13 commits October 28, 2026 08:26
Squashed and rebased onto main. Adds the first-run onboarding page (agents,
GitHub, project), the daemon-owned GitHub device sign-in (code shown in the
page, no terminal), and the supporting hooks, i18n strings and tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XhB8WKCryTGjCMULBJyhwK
…, drop header logo

- Remove the small AO mark from the onboarding header; the progress bars stay put.
- Offer 'Start a standalone agent' on the project step. It skips the project, keeps
  the chosen agent, and ends on the Scratchpad composer.
- Once an orchestrator agent is chosen, show a Worker agent dropdown that follows it
  by default, with a hint that it can differ.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XhB8WKCryTGjCMULBJyhwK
…ording

The onboarding "Sign in with GitHub" step spun forever with gh 2.102.0. The
daemon runs `gh auth login --web` without a terminal and parses the one-time
code from gh's output, but only matched the old wording:

    ! First copy your one-time code: ABCD-1234

Newer gh copies the code to the clipboard itself and prints:

    ! One-time code (5D0D-70F8) copied to clipboard

No code was ever found, so the attempt stayed in `starting` until the
15-minute timeout and the UI showed its loader the whole time.

Parsing no longer depends on gh's wording:
- Code: the first XXXX-XXXX token (uppercase letters and digits) gh prints.
  Tokens inside a link are skipped, and once a code is found nothing later
  replaces it.
- Verification URL: the first https:// link gh prints, in any order relative
  to the code. The line no longer has to contain "URL". The
  https://github.com/login/device default still applies when gh prints none.
- ANSI color codes are stripped before matching. With CLICOLOR_FORCE=1 in the
  environment, gh wraps the code in escapes and the code was never found.

Tests cover the old wording, the gh 2.102 clipboard wording, unfamiliar
wording with decoy code-shaped tokens, and colored output with CRLF line
endings. Also checked against a real gh 2.102.0 run, with and without
CLICOLOR_FORCE=1.

Known gap: if gh never prints a recognizable code (a future code format, or
gh stalling), the step still waits out the 15-minute timeout instead of
failing fast.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…#7021)

* fix(onboarding): round the connected GitHub card and explain a failed gh install

The connected row is now a standalone rounded card, and a failed install shows
a plain sentence instead of the job's raw error (e.g. "exit status 1").

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xymr7J3GubQA154hpXTfra

* feat(onboarding): start the standalone agent as soon as onboarding finishes

Choosing a standalone agent used to end on the Scratchpad composer and wait
for a prompt. The finish step now spawns the worker itself and opens its
session. A spawn failure goes back to onboarding with the choices kept.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TPBEDgCx2B9aYDe7t1um6X

* test(onboarding): pass the standalone session dep in the finish tests

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TPBEDgCx2B9aYDe7t1um6X

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
…er rebasing on main

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BAocjSaz4VhDWFC8rdb8c2
@ronishrohan
ronishrohan force-pushed the codex/reopen-onboarding branch from 64d7a21 to a425fef Compare October 28, 2026 02:58
@ronishrohan

Copy link
Copy Markdown
Collaborator Author

Closing: replaced by #7657, which builds on #7569.

@ronishrohan ronishrohan closed this Nov 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

comp/desktop Electron main process and React renderer. enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants