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