Hanzi Browse

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

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:

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

Disambiguation from other tools you may have

You probably have multiple browser-ish or web-ish tools available. Here's when to pick which:

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