OAuth setup UX improvements needed

[KHAEntertainment]

Problem

The OAuth setup flow has UX issues that prevent smooth first-time configuration:

Issue 1: Port conflict handling

When port 3000 is already in use, the script fails with no auto-retry or alternative port.

Issue 2: macOS compatibility

The setup script uses timeout command which is not available on macOS by default.

Issue 3: Browser doesn't auto-open

The script prints the authorization URL but does NOT automatically open it in the browser. User must manually copy-paste the URL.

Expected behavior: On macOS, script should call open <auth_url> to launch browser automatically. On Linux, use xdg-open. On Windows, use start.

Issue 4: PKCE codes are single-use (OpenRouter limitation)

When OAuth fails mid-flow (browser closed, timeout, etc.), the same PKCE verifier cannot be reused. User must re-authorize but the old code is invalidated. This causes repeated "400 Bad Request" errors on token exchange.

Issue 5: Fallback for API key acceptance in-chat (needed)

This should be a fallback only, not the primary flow.

Add a /grok-swarm:set-key YOUR_API_KEY command that:

• Saves the key directly to ~/.config/grok-swarm/config.json
• MUST warn the user explicitly that they are voluntarily exposing their API key into the Claude context stream
• Should only be offered as a last resort when OAuth fails repeatedly

Proposed Solutions

Issue 3: Auto-open browser

1. Use Python's webbrowser module which is cross-platform:

import webbrowser
webbrowser.open(auth_url)

2. Or use platform-specific commands:
   • macOS: subprocess.run(['open', auth_url])
   • Linux: subprocess.run(['xdg-open', auth_url])
   • Windows: subprocess.run(['start', auth_url], shell=True)

Issue 1 & 2: (same as before)

• Add --port CLI argument, try alternative ports if busy
• Detect OS and use appropriate timeout mechanism

Issue 4: PKCE single-use

• Add retry logic with fresh PKCE pair when token exchange fails
• Or document clearly that user must complete OAuth in single session

Issue 5: Fallback API key command

• Add /grok-swarm:set-key skill command
• Display explicit warning: "WARNING: You are about to paste your API key into the conversation. This will expose your key to the LLM context. Only proceed if you understand the risks."
• Save to config.json with proper permissions after warning acknowledged

Severity

Medium - Workaround exists (manual URL copy-paste) but reduces perceived polish.

Labels

• enhancement
• ux
• oauth

---

Updated from grok-swarm:setup session - added Issue 3: browser auto-open

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Warning

Insufficient credits. Please purchase more credits or upgrade your plan to continue using Traycer.

[KHAEntertainment]

Update: OAuth retry issue

Tested OAuth flow - found additional issue:

Issue 4: OAuth PKCE codes are single-use

The OAuth authorization code can only be used once. If the user:

1. Starts OAuth flow
2. Closes browser accidentally
3. Reopens browser with same URL

The token exchange fails with HTTP 400 because the code was already exchanged.

Root cause: The auth URL contains a code_challenge but when retrying, a new code_verifier is generated. The callback server keeps the old verifier, so it doesn't match.

Fix needed: Either:

1. Make the callback server handle multiple auth attempts within the timeout window
2. Add a --reuse flag that regenerates the same PKCE pair
3. Provide a single-use token that can be retried

Current workaround

Use manual key setup until this is fixed.

---

Session notes from OAuth testing