Hanzi Browse

Give your AI agent a real browser.

One tool call. Entire task delegated. Your agent clicks, types, fills forms,
reads authenticated pages — in your real signed-in browser.

Works with

Two ways to use Hanzi

Use it now — give your agent a browser

Build with it — embed browser automation in your product

Get Started

npx hanzi-browse setup

One command does everything:

npx hanzi-browse setup
│
├── 1. Detect browsers ──── Chrome, Brave, Edge, Arc, Chromium
│
├── 2. Install extension ── Opens Chrome Web Store, waits for install
│
├── 3. Detect AI agents ─── Claude Code, Cursor, Codex, Windsurf,
│                           VS Code, Gemini CLI, Amp, Cline, Roo Code
│
├── 4. Configure MCP ────── Merges hanzi-browse into each agent's config
│
├── 5. Install skills ───── Copies browser skills into each agent
│
└── 6. Choose AI mode ───── Managed ($0.05/task) or BYOM (free forever)

Managed — we handle the AI. 20 free tasks/month, then $0.05/task. No API key needed.
BYOM — use your Claude Pro/Max subscription, GPT Plus, or any API key. Free forever, runs locally.

Examples

"Go to Gmail and unsubscribe from all marketing emails from the last week"
"Apply for the senior engineer position on careers.acme.com"
"Log into my bank and download last month's statement"
"Find AI engineer jobs on LinkedIn in San Francisco"

Skills & Free Tools

Hanzi Browse has two distribution channels. Both use the same browser automation engine and site domain knowledge:

Skills — for users who run Hanzi locally through their AI agent. The setup wizard installs skills directly into your agent (Claude Code, Cursor, etc.). Each skill teaches the agent when and how to use the browser for a specific workflow.

Free Tools — hosted web apps that anyone can try without installing anything. Each tool is a standalone app built on the Hanzi API that demonstrates a use case. Every skill can become a free tool.

Skills

Installed automatically during npx hanzi-browse setup. Your agent reads these as markdown files.

Skill	Description
`hanzi-browse`	Core skill — when and how to use browser automation
`e2e-tester`	Test your app in a real browser, report bugs with screenshots
`social-poster`	Draft per-platform posts, publish from your signed-in accounts
`linkedin-prospector`	Find prospects, send personalized connection requests
`a11y-auditor`	Run accessibility audits in a real browser
`data-extractor`	Extract structured data from websites into CSV/JSON
`x-marketer`	Twitter/X marketing workflows

Open source — add your own.

Free Tools

Try them at tools.hanzilla.co. No account needed — just install the extension and go.

Tool	What it does	Try it
X Marketing	AI finds relevant conversations on X, drafts personalized replies, posts from your Chrome	tools.hanzilla.co/x-marketing

Site Domain Knowledge

Both skills and free tools rely on site patterns — verified interaction playbooks for complex websites. These document how to handle async loading, Draft.js editors, anti-bot detection, and other site-specific quirks.

Currently available: x.com. Contribute patterns for other sites.

Build with Hanzi Browse

Embed browser automation in your product. Your app calls the Hanzi API, a real browser executes the task, you get the result back.

Get an API key — sign in to your developer console, then create a key
Pair a browser — create a pairing token, send your user a pairing link (/pair/{token}) — they click it and auto-pair
Run a task — POST /v1/tasks with a task and browser session ID
Get the result — poll GET /v1/tasks/:id until complete, or use runTask() which blocks

import { HanziClient } from '@hanzi/browser-agent';

const client = new HanziClient({ apiKey: process.env.HANZI_API_KEY });

const { pairingToken } = await client.createPairingToken();
const sessions = await client.listSessions();

const result = await client.runTask({
  browserSessionId: sessions[0].id,
  task: 'Read the patient chart on the current page',
});
console.log(result.answer);

API reference · Dashboard · Sample integration

Tools

Tool	Description
`browser_start`	Run a task. Blocks until complete.
`browser_message`	Send follow-up to an existing session.
`browser_status`	Check progress.
`browser_stop`	Stop a task.
`browser_screenshot`	Capture current page as image.

Pricing

	Managed	BYOM
Price	$0.05/task (20 free/month)	Free forever
AI model	We handle it (Gemini)	Your own key
Data	Processed on Hanzi servers	Never leaves your machine
Billing	Only completed tasks. Errors are free.	N/A

Building a product? Contact us for volume pricing.

Development

Prerequisites: Node.js 18+, Docker Desktop (must be running before make fresh).

First time (local setup)

git clone https://github.com/hanzili/hanzi-browse
cd hanzi-browse
make fresh

Performs full setup: installs deps, builds server/dashboard/extension, starts Postgres, runs migrations, and launches the dev server (~90s).

Run the project

make dev

Starts the backend services (Postgres + migrations + API server) and serves the dashboard UI.

API: http://localhost:3456
Dashboard (requires Google OAuth): http://localhost:3456/dashboard

Configuration

The defaults in .env.example are enough to run the server.

Optional services:

Google OAuth (dashboard sign-in) -- add GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET to .env
Stripe (credit purchases) -- add test keys to .env
Vertex AI (managed task execution) -- see .env.example for setup steps

Load the extension

Open chrome://extensions, enable Developer Mode, click "Load unpacked", and select the project root (the folder that contains manifest.json).

Verify everything works

After make dev is running and the extension is loaded, test both user paths:

Test 1: MCP / CLI mode (user path)

# In a separate terminal:
node server/dist/cli.js start "Go to example.com and tell me the page title"

You should see a Chrome window open, the agent navigate to example.com, and return the page title. If this works, the relay + extension + agent loop are all connected.

Test 2: Managed API mode (developer path)

# 1. Check the API is running
curl http://localhost:3456/v1/health

# 2. Open the dashboard and sign in (requires Google OAuth configured)
open http://localhost:3456/dashboard

# 3. Create an API key from the dashboard, then:
curl -X POST http://localhost:3456/v1/browser-sessions/pair \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# 4. Open the pairing URL in Chrome (from the response)
open "http://localhost:3456/pair/PAIRING_TOKEN"

# 5. After pairing, run a task
curl -X POST http://localhost:3456/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Go to example.com and read the title", "browser_session_id": "SESSION_ID"}'

# 6. Check the result
curl http://localhost:3456/v1/tasks/TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Test 3: Embed widget

Create a test HTML file and open it in Chrome:

<div id="hanzi"></div>
<script src="http://localhost:3456/embed.js"></script>
<script>
  HanziConnect.mount('#hanzi', {
    apiKey: 'YOUR_PUBLISHABLE_KEY',
    apiUrl: 'http://localhost:3456',
    onConnected: (id) => console.log('Connected:', id),
    onError: (err) => console.log('Error:', err),
  });
</script>

You should see the pairing widget with step-by-step instructions.

Notes

Local vs CLI usage -- npx hanzi-browse setup is for packaged usage and may not work in a local clone
Port conflicts -- if you see EADDRINUSE on 3456, stop existing processes or run make stop
No Google OAuth? -- The dashboard sign-in won't work, but you can seed a test workspace directly in the database and use the API key for testing

Commands

Command	What it does
`make fresh`	Full first-time setup (deps + build + DB + start)
`make dev`	Start everything (DB + migrate + server)
`make build`	Rebuild server + dashboard + extension
`make stop`	Stop Postgres
`make clean`	Stop + delete database volume
`make check-prereqs`	Verify Node 18+ and Docker are available
`make help`	Show all commands

Contributing

We welcome contributions! See CONTRIBUTING.md for setup instructions.

Good first contributions: new skills, landing pages, site-pattern files, platform testing, translations. Check the open issues.

Community

Discord · Documentation · Twitter

Privacy

Hanzi operates in different modes with different data handling. Read the privacy policy.

BYOM: No data sent to Hanzi servers. Screenshots go to your chosen AI provider only.
Managed / API: Task data processed on Hanzi servers via Google Vertex AI.

License

Polyform Noncommercial 1.0.0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Hanzi Browse

Two ways to use Hanzi

Use it now — give your agent a browser

Build with it — embed browser automation in your product

Get Started

Examples

Skills & Free Tools

Skills

Free Tools

Site Domain Knowledge

Build with Hanzi Browse

Tools

Pricing

Development

First time (local setup)

Run the project

Configuration

Load the extension

Verify everything works

Notes

Commands

Contributing

Community

Privacy

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Hanzi Browse

Two ways to use Hanzi

Use it now — give your agent a browser

Build with it — embed browser automation in your product

Get Started

Examples

Skills & Free Tools

Skills

Free Tools

Site Domain Knowledge

Build with Hanzi Browse

Tools

Pricing

Development

First time (local setup)

Run the project

Configuration

Load the extension

Verify everything works

Notes

Commands

Contributing

Community

Privacy

License