chromeflow CLAUDE.md

Chromeflow — Claude Instructions

What chromeflow is

Chromeflow is a browser guidance tool. When a task requires the user to interact with a website (create accounts, set up billing, retrieve API keys, configure third-party services), use chromeflow to guide them through it visually instead of giving text instructions.

When to use chromeflow (be proactive)

Use chromeflow automatically whenever a task requires:

• Creating or configuring a third-party account (Stripe, SendGrid, Supabase, Vercel, etc.)
• Retrieving API keys, secrets, or credentials to place in .env
• Setting up pricing tiers, webhooks, or service configuration in a web UI
• Any browser-based step that is blocking code work

Do NOT ask "should I open the browser?" — just do it. The user expects seamless handoff.

Never end a response with a "you still need to" list of browser tasks. If code changes are done and browser steps remain (e.g. creating a Stripe product, adding an env var), continue immediately with chromeflow — don't hand them back to the user.

HARD RULES — never break these

1. Never use Bash as a fallback for browser tasks. If click_element fails, use scroll_to_element then retry, or use highlight_region to show the user. Never use osascript, applescript, or any shell command to control the browser.

2. Never use take_screenshot to read page content. After click_element, after navigation — always call get_page_text (or find_text if you only need to check for a specific phrase). get_page_text returns up to 10,000 characters; if truncated it tells you the next startIndex to paginate. Screenshots are only for locating an element's pixel position when DOM queries have already failed. Never take more than 1–2 screenshots in a row.

3. Use wait_for(selector=…) to wait for async page changes (build completion, modals, toasts). Never poll with repeated take_screenshot calls.

4. Form submits on social/auth platforms require a real human click. Reddit, X / Twitter, GitHub device-code, mcp.so, and most modern anti-bot-protected sites silently reject synthetic submit clicks — click_element returns success but nothing happens. For known anti-bot platforms: pre-fill the form via fill_form/fill_input, then highlight_region the submit button and call wait_for_click() so the user's real gesture fires the submit. To detect this case on an unknown form, pass expect_submit: true on the submit click — chromeflow returns success=false with "submit silently rejected" when no URL change / toast / alert / modal appears within 4s. Do NOT retry a silent rejection; switch straight to highlight + wait_for_click.