Skip to content

Make first-run linking one line and fix four places new users got stuck - #233

Merged
TeoSlayer merged 2 commits into
TeoSlayer:mainfrom
pstayets:onboarding-tiny-fixes
Nov 12, 2026
Merged

TeoSlayer merged 2 commits into
TeoSlayer:mainfrom
pstayets:onboarding-tiny-fixes

Conversation

@pstayets

Copy link
Copy Markdown
Contributor

Why

I ran a first-run test as a brand-new user: sign up on a phone, link a Mac from a fresh HOME on a stock PATH, then start Claude Code from the phone. It works, but a new user gets stuck in five places on the way. This PR fixes all five. None of them changes how sessions, encryption or the relay work.

What changes for users

Where they got stuck Before After
shell not found after install On a stock Mac ~/.local/bin isn't on PATH, so the separate shell auth step fails with "command not found" The installer runs whatever follows sh -s -- with the new executable's full path: curl -fsSL https://shell.online/install | sh -s -- auth --allow-remote-start. Piped into sh, the command gets /dev/tty for its prompts. With no arguments the installer behaves exactly as before.
Browser starts not allowed The empty-page steps say shell auth, whose prompt is [y/N], so pressing Enter means the browser can't start sessions The empty Sessions and Machines pages show the one line above, which includes --allow-remote-start
Sign-in loses the CLI request The sign-up page's header "Sign in" link dropped router state (the foot link kept it), so signing in landed on Sessions and the terminal kept waiting AuthShell passes location.state through the header link
shell auth times out 5 minutes wasn't enough to sign in, create a vault and confirm the recovery key; the browser then hit a dead loopback URL 15 minutes, and a timeout now says to run shell auth again
Phone top bar The wordmark slid under "+ Session": 52px of overlap at 360px, 22px at 390px (measured on production). The empty-list command scrolled off the edge. The wordmark keeps its width and the gaps and action get smaller; under 375px the button shows only "+" and keeps its label for screen readers. The command wraps.

The phone layout was checked by injecting this exact CSS into app.shell.online at 360, 390 and 430px. There's no overlap at any width, the row stays inside the viewport, and the command has no hidden overflow.

Security

  • The installer only runs a command when the person puts one after sh -s --, and it runs the binary it just verified against SHA256SUMS. Nothing runs by default.
  • --allow-remote-start is the existing, documented flag. It now appears on the account pages whose only purpose is starting sessions from the browser. Consent is still given in the terminal, by the person pasting the command.
  • The longer loopback wait doesn't widen the one-time PKCE request, and the listener is still bound to 127.0.0.1.

Tests

  • scripts/test-install.sh: a new scenario with arguments (runs the command by full path, skips the "Next" steps) and one without (unchanged). It fails against the old installer.
  • app/src/components/AuthShell.test.ts: the header link carries { from }. It fails without the fix.
  • app/src/lib/setup-command.test.ts, internal/account/login_test.go: the timeout is at least 15 minutes and the message says what to do.
  • Local: npm run check (485 tests, installer, SEO, mobile, formula), npm run build:web, app typecheck/lint/test (1,788 passed; lint warnings unchanged from main at 54), go vet, gofmt, go test -race ./....
  • End to end on macOS: cat public/install | sh -s -- auth --allow-remote-start in a pty with the published 0.22.0 binary installed, ran shell auth on a stock PATH, and the machine linked with browser starts allowed, without a prompt.

Not covered: install.ps1 doesn't take arguments yet (Windows wasn't tested). README, docs/content.json (app page) and CHANGELOG are updated.

🤖 Generated with Claude Code

@pstayets
pstayets requested a review from TeoSlayer as a code owner September 22, 2026 20:41

@Alexgodoroja Alexgodoroja left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thanks. The AuthShell state fix, the 15-minute timeout and the installer's argument forwarding are all useful. With no arguments, the installer's output is byte-for-byte what it was, and the arguments are passed safely with exec "$target" "$@". I can't merge this yet, though. main has moved about 33 commits since you opened it and now conflicts in 4 files. Two of those changes also clash with what landed since.

Conflicts / superseded by main

  • app/src/routes/Workspace.tsx: #234/#242 replaced the empty Sessions list with SessionStartGuide. It has a macOS/Linux and Windows toggle and deliberately uses a plain shell auth (see the comment "The same path works without authorizing remote process creation"). The PR's SETUP_COMMAND list no longer has anywhere to go. Please drop this hunk and keep main's guide.
  • app/src/styles/shell.css: #242 already fixed the top bar. Under 760px .new-session is an icon-only 44x44 button with aria-label and .new-session-label { display: none }. This auto-merges without a conflict, but at 760px and below .topbar-right .new-session { height: 38px; padding: 0 11px } beats main's .new-session { height: 44px; padding: 0 } on specificity. That shrinks the touch target below the 44px main keeps on purpose. Please drop the whole shell.css hunk.
  • README.md / docs/content.json: both were restructured, and the install table and the "Link a machine" card are gone. If you want the one-liner in the docs, it needs to go into the new "1. Link your computer" card on the app page.
  • Product question for maintainers: main's docs now say remote start "grants remote execution authority; choose it deliberately". The Machines empty state would put --allow-remote-start into the default copy-paste line. Someone needs to decide that on purpose, not have it arrive through a merge.

Installer bugs (public/install, the new if [ "$#" -gt 0 ] block)

  1. exec replaces the shell, so trap 'rm -rf "$temporary_dir"' EXIT never fires. Every run with arguments leaves $TMPDIR/shell-online.XXXXXX/{shell,SHA256SUMS} behind. I reproduced it: the leftover directory is still there after a run with arguments. Fix: rm -rf "$temporary_dir"; trap - EXIT HUP INT TERM before the exec.
  2. With no terminal (CI, ssh without -t), the fallback exec "$target" "$@" gives the command the rest of the installer script on stdin. I reproduced it: the child read printf '\nNext:.... A [y/N] prompt then reads script text. Use </dev/null in that branch.

With those two fixes and the conflicts resolved in main's favour, everything passes locally: root typecheck and vitest (733/733), scripts/test-install.sh, app tsc and vitest (1896 passed, 3 skipped), go vet, go test ./internal/account, and the layout/mobile browser checks.

@pstayets
pstayets force-pushed the onboarding-tiny-fixes branch from a89ee91 to 0c24098 Compare September 25, 2026 16:58
@pstayets

Copy link
Copy Markdown
Contributor Author

Thanks for the careful review. Rebased onto main as one commit, with every conflict resolved in main's favour: SessionStartGuide and main's top bar are untouched, and the shell.css hunk is gone. The one-liner lives in the "1. Link your computer" card instead of the README.

On the product question I dropped --allow-remote-start from the copy-paste line, so remote start stays a choice made at the prompt, and a test pins that. Both installer bugs are fixed: the temporary directory is removed before the exec, and without a terminal the command gets </dev/null. The new installer scenarios fail on the previous installer.

The windows check failure looks unrelated: this PR touches neither install.ps1 nor scripts/test-install-windows.ps1, and the job passed on main's last eight runs. The test's local Python server refused the first request within its 10-second startup window. Could someone with admin rights re-run the failed job? I can't from my account.

A first-run test from a phone sign-up to Claude Code started from the phone
hit each of these:

- The installer can now run a shell command after installing, by the new
  executable's full path: `curl ... | sh -s -- auth`. On a stock Mac the
  install directory is not on PATH, so the separate `shell auth` step failed
  with command not found. Piped into sh, the command gets /dev/tty for its
  prompts, or no input at all when there is no terminal, never the rest of
  the script. exec replaces the installer's shell, so it removes its
  temporary directory before, not on an EXIT trap that would never fire.
- The empty Machines page and the app guide's "1. Link your computer" card
  show that one line. Remote start is left out of it on purpose: it grants
  remote execution authority, so it stays a choice made at the prompt.
- The sign-up page's header "Sign in" link now carries router state, as the
  foot link already did, so signing in returns to the CLI's link request
  instead of the sessions list.
- `shell auth` waits 15 minutes instead of 5 (sign-in, vault creation and
  recovery-key confirmation ran past 5) and says to run it again on timeout.
- The empty-list command wraps instead of running off the edge of a phone.

Rebased onto main: the Sessions empty state is main's SessionStartGuide, the
top bar is main's (TeoSlayer#242), and README and docs keep main's structure.

Tests: installer scenarios for the post-install command, its stdin without a
terminal and its temporary directory; AuthShell header link state; setup
command, remote start excluded; login timeout and message.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@TeoSlayer
TeoSlayer force-pushed the onboarding-tiny-fixes branch from 0c24098 to 50030ec Compare November 12, 2026 19:04
@TeoSlayer
TeoSlayer merged commit 66dad2e into TeoSlayer:main Nov 12, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants