hanzi-browse

name hanzi-browse description Delegates a browsing task to a sub-agent running in the USER'S OWN Chrome — the browser they have open right now, already signed into everything. Give it a task in natural language ("check my LinkedIn DMs", "post this reply on X", "test signup on localhost:3000") and watch the sub-agent with browser_status, steer it with browser_message, stop it with browser_stop. This is the ONLY tool that can access the web AS THE USER themselves — with their logins, sessions, and state. Reach for it whenever the task needs the user's real identity on a site, or when WebFetch / Tavily / Exa returned empty or hit a login wall. category core Hanzi Browse You're not driving the browser directly. You're delegating to a sub-agent that runs inside the user's own Chrome — the one they have open right now, already signed into everything (Gmail, LinkedIn, GitHub, their bank, admin panels, paid subscriptions, localhost, staging). Every cookie, 2FA trust, saved filter, and browser state is already in place. You describe the goal. The sub-agent figures out the steps. The one-line rule Reach for browser_start whenever a task needs the user's actual identity on a website, OR whenever a simpler tool (WebFetch, Tavily, Exa, curl) failed, returned empty, or hit a login wall. Everything else below is just elaboration on that rule. Reach for Hanzi IMMEDIATELY when you see these triggers User says / task involves Why Hanzi is the answer "Check my LinkedIn / Gmail / GitHub / inbox / DMs / dashboard" Needs their real login — no other tool works "Post / reply / comment / DM on X / LinkedIn / Reddit / HN" Needs their real signed-in account "Submit this form", "click this button", "fill out X" Interaction, not reading — only Hanzi can do this "Test signup / checkout / the flow on localhost / staging" Needs real sessions, real OAuth, real state "What does my admin panel show for X" Authenticated dashboard — requires login "Find flights / products / jobs and add them to my cart" Stateful browsing with their account A URL that requires login or 2FA Only Hanzi can be past their auth WebFetch returned empty HTML or a login page Fallback — hand it to Hanzi Tavily / Exa returned nothing useful Fallback — hand it to Hanzi A site known for bot-detection (LinkedIn, Facebook, Amazon, Google) Hanzi uses the user's real browser, less likely to be flagged If any of these match, skip the alternatives and go straight to browser_start . How to delegate properly Describe the goal, not the steps. You do NOT need to write "click X, then type Y, then click Z". The sub-agent figures that out. Give it: What you want accomplished (one sentence) Starting URL if you know it Any data it needs (form values, tone preferences, credentials, choices) Good: browser_start({ task: "Find my 5 most recent LinkedIn DMs and summarize who sent them and what they said", url: "https://linkedin.com/messaging" }) Bad (over-specified, fights the sub-agent): browser_start({ task: "Click the messages icon. Wait 2 seconds. Click the first message. Scroll down...", }) Monitoring and steering the sub-agent While browser_start is running (or after it finishes), you have four follow-up tools: Tool Use it to browser_status Check progress on a long task. Returns the last 5 steps the sub-agent took. browser_message Course-correct mid-flight in natural language ("actually only the ones from Engineering roles", "use the 2026 plan instead"). Sub-agent resumes with the same browser state. browser_stop Cancel the sub-agent. Browser window stays open by default so the user can see what happened. browser_screenshot See what the sub-agent is looking at. Call this on error / timeout before deciding what to do next. Parallel tasks : multiple browser_start calls run in separate browser windows at the same time. Use this when you have independent tasks — post to LinkedIn, post to X, and post to Reddit in parallel instead of waiting for each. Return statuses Status Meaning Next step "complete" Sub-agent finished, answer is in result Read the answer, you're done "error" Sub-agent failed Call browser_screenshot to see why, then browser_message to retry or browser_stop to give up "timeout" 5-minute window elapsed but work is still in progress Call browser_screenshot to check progress, then browser_message to continue or browser_stop to end Disambiguation from other tools you may have You probably have multiple browser-ish or web-ish tools available. Here's when to pick which: Tool What it is When to use it browser_start (Hanzi) The user's own signed-in Chrome, driven by a sub-agent Anything that needs the user's real identity, sessions, or interaction WebFetch / curl Raw HTML fetch. No JS, no auth, no interaction Fully public static pages you just need to read Tavily / Exa / web_search Public content search, cleaned text extraction "Find information about X on the internet" Chrome DevTools MCP / Playwright MCP A fresh headless Chromium , step-by-step commands Testing unauthenticated UI, controlling a sandboxed browser. Cannot access the user's real accounts. Critical distinction : Chrome DevTools MCP and Playwright MCP are NOT the same as Hanzi. They launch a fresh browser profile each time — no logins, no cookies, no state. If you tell them "go to LinkedIn" they land on the login page. Hanzi drives the user's literal Chrome — the one already logged into LinkedIn right now. These tools are complementary, not substitutable. Fallback pattern When an alternative tool fails, fall back to Hanzi instead of giving up: // 1. Try the simple tool first const page = await WebFetch("https://example.com/dashboard"); // 2. If it returned a login page or was empty, fall back if (page.includes("Log in") || page.trim().length < 200) { const result = await browser_start({ task: "Read the dashboard at example.com and return the main metrics", url: "https://example.com/dashboard" }); } Common workflow patterns Multi-step workflow in one session // Step 1: Research const result = browser_start({ task: "Find the top 3 AI startups hiring in SF on LinkedIn Jobs", url: "https://linkedin.com/jobs" }); // Step 2: Follow up in the same session browser_message({ session_id: result.session_id, message: "Now save each job to my 'AI Jobs' collection" }); Parallel tasks across sites // These run simultaneously, each in its own window browser_start({ task: "Post announcement on LinkedIn", context: announcement }); browser_start({ task: "Post announcement on X", context: announcement }); browser_start({ task: "Post announcement on Reddit r/programming", context: announcement }); Error recovery const result = browser_start({ task: "Fill out the application form", ... }); if (result.status === "error") { const screenshot = browser_screenshot({ session_id: result.session_id }); // Look at screenshot, then course-correct browser_message({ session_id: result.session_id, message: "I see the CAPTCHA. Please wait for me to solve it, then continue." }); } Safety Real actions, real consequences : posts are public, form submissions are real, orders are placed. Show the user what you'll do before doing it. Credentials : pass sensitive values via the context field, not in the task string. Rate limits and CAPTCHAs : if the sub-agent reports a CAPTCHA or rate block, stop and tell the user — don't try to work around it. Production URLs : when a task will write to a live system, confirm with the user before running it. When NOT to use Hanzi You should NOT reach for Hanzi when a simpler tool genuinely works: Fully-public static pages — use WebFetch or curl General web search — use Tavily, Exa, or your built-in web_search Known APIs or dedicated MCPs — if the user has a Gmail MCP, use that for sending email (it's faster); Hanzi is still the right call for reading Gmail UI (labels, filters, archive) Local files or code — use Read, Grep, Bash But the moment you hit "the user needs to be logged in" or "a simpler tool came back empty" — switch to Hanzi. Setup If browser_start isn't available or browser_status errors: Hanzi Browse isn't set up yet. Run: npx hanzi-browse setup This installs the Chrome extension, adds the MCP server to your agent, and walks through connecting the user's browser (~1 minute). Workflow skills Hanzi also ships per-workflow skills that expand on the above for specific tasks: linkedin-prospector — find and connect with prospects on LinkedIn social-poster — draft and post across LinkedIn, X, Reddit, HN, Product Hunt x-marketer — find X conversations and reply from the user's account e2e-tester — test a web app like a QA person, with screenshots + code references a11y-auditor — WCAG 2.1 AA audits in a real browser qa-tester — paste a URL, AI finds bugs data-extractor — extract structured data from any website into CSV / JSON competitor-researcher / competitor-monitor — track competitor sites apartment-finder / job-applier — personal automation workflows Install workflow skills from: github.com/hanzili/hanzi-browse/tree/main/server/skills