feat(onboarding): ask users to choose coding agent#347
Conversation
Summary: - replace fixed Claude/Codex setup shortcuts with an explicit coding-agent chooser in onboarding notes - extend setup terminal actions for Claude, Codex, OpenCode, Gemini CLI, and shell-only setup while showing manual guidance for unsupported choices - align the landing prompt, public skills.md, local Matrix skill, onboarding plugin skill, and developer workflow docs around detect + confirm behavior - fix a React Doctor finding in MarkdownViewer and harden a flaky onboarding tool-pack timeout test Tests: - flox activate -- bun run typecheck - flox activate -- bun run check:patterns - flox activate -- npx react-doctor@latest shell - flox activate -- bun run test tests/gateway/onboarding-tool-packs.test.ts - flox activate -- bun run test tests/shell/manual-setup-stickers.test.tsx tests/shell/terminal-launch.test.ts tests/shell/markdown-viewer-svg.test.tsx - flox activate -- bun run test Invariants: - Source of truth: matrix run remains command-explicit; the onboarding chooser only drives guided UI/copy, not a saved CLI default. - Lock/transaction scope: no database writes or transactions are introduced by the onboarding agent-choice flow. - Acceptable orphan states: unsupported agent choices show manual setup guidance and do not claim launch or verification support. - Auth source of truth: installed/auth-needed suggestions still come from the existing /api/agents signal; no credentials or provider secrets are accepted in the UI. - Deferred scope: full auth/probe integrations for OpenClaw, Cursor/Cline, Custom, and other non-terminal agents remain out of scope.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
@greptile review this PR please |
Greptile SummaryThis PR replaces the fixed Claude/Codex setup shortcuts in the onboarding UI with an explicit eight-choice coding-agent picker, and extends
Confidence Score: 5/5Safe to merge — the changes are additive UI/copy updates with no database writes, no auth changes, and no regressions to existing terminal-launch flows. The core logic changes are contained to the onboarding sticker component and the terminal-launch lib. The rename from claude-login/codex-login to the agent-* scheme is consistent across source, regex, and tests. The /api/agents fetch is properly guarded with an AbortController, a mounted flag, and a 10-second timeout. The MarkdownViewer fix correctly applies the React render-time state-adjustment pattern. The gemini detection gap and agent-shell test gap both flagged in previous review rounds are addressed here. No files require special attention. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[ManualSetupStickers mounts] --> B[fetch /api/agents]
B --> C{Response ok?}
C -- No / timeout --> D[suggestedAgent = null]
C -- Yes --> E[parseSuggestedAgent]
E --> F{Any agent installed + authState ok/required?}
F -- No --> D
F -- Yes --> G[suggestedAgent = first match from CODING_AGENT_CHOICES order]
G --> H[Render agent grid with Suggested badge]
D --> H
H --> I{User clicks choice}
I -- has launchAction --> J[createTerminalLaunchPath / onOpenTerminal]
I -- no launchAction --> K[setSelectedManualCopy / show inline guidance]
J --> L[Terminal opens with agent-claude / agent-codex / agent-opencode / agent-gemini / agent-shell / github-ssh-login]
Reviews (4): Last reviewed commit: "fix(onboarding): suggest detected gemini..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| return null; | ||
| } | ||
| const agents = (value as { agents: unknown[] }).agents; | ||
| for (const candidate of ["claude", "codex", "opencode"] as const) { |
There was a problem hiding this comment.
parseSuggestedAgent checks only ["claude", "codex", "opencode"] but omits "gemini", even though Gemini CLI has a full terminal launch action (agent-gemini) and appears as a first-class choice in CODING_AGENT_CHOICES. If the /api/agents endpoint returns a Gemini entry with installed: true and a recognized authState, the "Suggested" badge will never render for it — silently breaking the detection feature for Gemini users.
| for (const candidate of ["claude", "codex", "opencode"] as const) { | |
| for (const candidate of ["claude", "codex", "opencode", "gemini"] as const) { |
Prompt To Fix With AI
This is a comment left during a code review.
Path: shell/src/components/onboarding/ManualSetupStickers.tsx
Line: 128
Comment:
`parseSuggestedAgent` checks only `["claude", "codex", "opencode"]` but omits `"gemini"`, even though Gemini CLI has a full terminal launch action (`agent-gemini`) and appears as a first-class choice in `CODING_AGENT_CHOICES`. If the `/api/agents` endpoint returns a Gemini entry with `installed: true` and a recognized `authState`, the "Suggested" badge will never render for it — silently breaking the detection feature for Gemini users.
```suggestion
for (const candidate of ["claude", "codex", "opencode", "gemini"] as const) {
```
How can I resolve this? If you propose a fix, please make it concise.
Greptile SummaryThis PR replaces the fixed Claude/Codex login shortcuts in the onboarding sticker with an explicit 8-choice coding-agent picker, extends
Confidence Score: 4/5Safe to merge; the agent-chooser flow is additive and does not touch auth, data persistence, or any server-side logic. The core change is straightforward UI wiring. The one functional gap is that ManualSetupStickers.tsx — the parseSuggestedAgent candidates list; tests/shell/terminal-launch.test.ts — missing agent-shell roundtrip assertion. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[ManualSetupStickers mounts] --> B[fetch /api/agents]
B -->|ok + agent found| C[parseSuggestedAgent\ncandidates: claude, codex, opencode]
B -->|error / timeout| D[suggestedAgent = null]
C -->|match found| E[setSuggestedAgent\nshows Suggested badge]
C -->|no match| D
E --> F[User sees 8-choice grid]
D --> F
F -->|Claude/Codex/OpenCode/Gemini/Shell| G{choice.launchAction?}
F -->|OpenClaw/Cursor-Cline/Custom| H[setSelectedManualCopy\nshow inline guidance]
G -->|yes| I[createTerminalLaunchPath action]
I --> J[onOpenTerminal called\nopens terminal tab]
J --> K[parseTerminalLaunchPath\nvalidates path regex]
K --> L[TerminalLaunchConfig\ncommand executed]
Prompt To Fix All With AIFix the following 2 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 2
shell/src/components/onboarding/ManualSetupStickers.tsx:128
`parseSuggestedAgent` checks `["claude", "codex", "opencode"]` but omits `"gemini"`. All four of those IDs are backed by a `launchAction` in `CODING_AGENT_CHOICES`, yet if the `/api/agents` endpoint returns a Gemini CLI entry with `installed: true`, no "Suggested" badge will ever appear for it. The three other terminal-launch agents were clearly included intentionally (opencode was added alongside this PR), so this looks like an oversight.
```suggestion
for (const candidate of ["claude", "codex", "opencode", "gemini"] as const) {
```
### Issue 2 of 2
tests/shell/terminal-launch.test.ts:17-38
**`agent-shell` not exercised in roundtrip test**
`agent-shell` is the only new terminal-launch action that isn't covered by the `maps onboarding setup actions to startup commands` test. A typo in its `command` field or a regex gap would be invisible until a user actually clicks "Shell only".
Reviews (2): Last reviewed commit: "feat(onboarding): ask users to choose co..." | Re-trigger Greptile |
| return null; | ||
| } | ||
| const agents = (value as { agents: unknown[] }).agents; | ||
| for (const candidate of ["claude", "codex", "opencode"] as const) { |
There was a problem hiding this comment.
parseSuggestedAgent checks ["claude", "codex", "opencode"] but omits "gemini". All four of those IDs are backed by a launchAction in CODING_AGENT_CHOICES, yet if the /api/agents endpoint returns a Gemini CLI entry with installed: true, no "Suggested" badge will ever appear for it. The three other terminal-launch agents were clearly included intentionally (opencode was added alongside this PR), so this looks like an oversight.
| for (const candidate of ["claude", "codex", "opencode"] as const) { | |
| for (const candidate of ["claude", "codex", "opencode", "gemini"] as const) { |
Prompt To Fix With AI
This is a comment left during a code review.
Path: shell/src/components/onboarding/ManualSetupStickers.tsx
Line: 128
Comment:
`parseSuggestedAgent` checks `["claude", "codex", "opencode"]` but omits `"gemini"`. All four of those IDs are backed by a `launchAction` in `CODING_AGENT_CHOICES`, yet if the `/api/agents` endpoint returns a Gemini CLI entry with `installed: true`, no "Suggested" badge will ever appear for it. The three other terminal-launch agents were clearly included intentionally (opencode was added alongside this PR), so this looks like an oversight.
```suggestion
for (const candidate of ["claude", "codex", "opencode", "gemini"] as const) {
```
How can I resolve this? If you propose a fix, please make it concise.| it("maps onboarding setup actions to startup commands", () => { | ||
| vi.spyOn(Date, "now").mockReturnValue(1_779_788_800_000); | ||
|
|
||
| expect(parseTerminalLaunchPath(createTerminalLaunchPath("claude-login"))).toMatchObject({ | ||
| label: "Claude login", | ||
| expect(parseTerminalLaunchPath(createTerminalLaunchPath("agent-claude"))).toMatchObject({ | ||
| label: "Claude Code setup", | ||
| command: "claude", | ||
| claudeMode: true, | ||
| }); | ||
| expect(parseTerminalLaunchPath(createTerminalLaunchPath("codex-login"))).toMatchObject({ | ||
| label: "Codex login", | ||
| expect(parseTerminalLaunchPath(createTerminalLaunchPath("agent-codex"))).toMatchObject({ | ||
| label: "Codex setup", | ||
| command: "codex", | ||
| }); | ||
| expect(parseTerminalLaunchPath(createTerminalLaunchPath("agent-opencode"))).toMatchObject({ | ||
| label: "OpenCode setup", | ||
| command: "opencode", | ||
| }); | ||
| expect(parseTerminalLaunchPath(createTerminalLaunchPath("agent-gemini"))).toMatchObject({ | ||
| label: "Gemini CLI setup", | ||
| command: "gemini", | ||
| }); | ||
| expect(parseTerminalLaunchPath(createTerminalLaunchPath("github-ssh-login"))?.command).toContain("gh auth login --hostname github.com --git-protocol ssh --web"); | ||
| }); |
There was a problem hiding this comment.
agent-shell not exercised in roundtrip test
agent-shell is the only new terminal-launch action that isn't covered by the maps onboarding setup actions to startup commands test. A typo in its command field or a regex gap would be invisible until a user actually clicks "Shell only".
Prompt To Fix With AI
This is a comment left during a code review.
Path: tests/shell/terminal-launch.test.ts
Line: 17-38
Comment:
**`agent-shell` not exercised in roundtrip test**
`agent-shell` is the only new terminal-launch action that isn't covered by the `maps onboarding setup actions to startup commands` test. A typo in its `command` field or a regex gap would be invisible until a user actually clicks "Shell only".
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Nima-Naderi
force-pushed
the
codex/agent-onboarding-choice
branch
from
ef3d263 to
463f20e
Compare
Nima-Naderi
force-pushed
the
codex/agent-onboarding-choice
branch
from
463f20e to
ec2ad53
Compare
1 participant
Summary:
Tests:
Invariants: