hanzi-in-chrome

<div align="center">

<img src="docs/logo.svg" width="80" alt="Hanzi Browse" />

# Hanzi Browse

**Give your AI agent a real browser.**

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

[![npm](https://img.shields.io/npm/v/hanzi-browse?color=%23cb3837&label=npm)](https://www.npmjs.com/package/hanzi-browse)
[![Chrome Web Store](https://img.shields.io/chrome-web-store/v/iklpkemlmbhemkiojndpbhoakgikpmcd?label=chrome%20web%20store&color=%234285F4)](https://chrome.google.com/webstore/detail/iklpkemlmbhemkiojndpbhoakgikpmcd)
[![Discord](https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/hahgu5hcA5)
[![License](https://img.shields.io/badge/license-PolyForm%20NC-green)](LICENSE)

**Works with**

<a href="https://claude.ai/code"><img src="https://browse.hanzilla.co/logos/claude-logo-0p9b6824.png" width="28" height="28" alt="Claude Code" title="Claude Code"></a>&nbsp;&nbsp;
<a href="https://cursor.com"><img src="https://browse.hanzilla.co/logos/cursor-logo-5jxhjn17.png" width="28" height="28" alt="Cursor" title="Cursor"></a>&nbsp;&nbsp;
<a href="https://openai.com/codex"><img src="https://browse.hanzilla.co/logos/openai-logo-6323x4zd.png" width="24" height="24" alt="Codex" title="Codex"></a>&nbsp;&nbsp;
<a href="https://ai.google.dev/gemini-api/docs/cls"><img src="https://browse.hanzilla.co/logos/gemini-logo-1f6kvbwc.png" width="24" height="24" alt="Gemini CLI" title="Gemini CLI"></a>&nbsp;&nbsp;
<img src="https://browse.hanzilla.co/logos/github-logo-tr9d8349.png" width="24" height="24" alt="VS Code" title="VS Code">&nbsp;&nbsp;
<img src="https://browse.hanzilla.co/logos/kiro-logo-wk3s9bcy.png" width="24" height="24" alt="Kiro" title="Kiro">&nbsp;&nbsp;
<img src="https://browse.hanzilla.co/logos/antigravity-logo-szj1gjgv.png" width="24" height="24" alt="Antigravity" title="Antigravity">&nbsp;&nbsp;
<img src="https://browse.hanzilla.co/logos/opencode-logo-svpy0wcb.png" width="24" height="24" alt="OpenCode" title="OpenCode">


<br/>

[![Watch demo](https://img.youtube.com/vi/3tHzg2ps-9w/maxresdefault.jpg)](https://www.youtube.com/watch?v=3tHzg2ps-9w)

</div>

<br/>

## Two ways to use Hanzi

### Use it now — give your agent a browser

![Use it now](docs/diagrams/use-it.svg)

### Build with it — embed browser automation in your product

![Build with it](docs/diagrams/build-with-it.svg)

<br/>

## Get Started

```bash
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.


<br/>

## 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"
```

<br/>

## 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 |
| `x-marketer` | Twitter/X marketing workflows |

Open source — [add your own](https://github.com/hanzili/hanzi-browse/tree/main/server/skills).

### Free Tools

Try them at [tools.hanzilla.co](https://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](https://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](server/site-patterns/x.com.md). Contribute patterns for other sites.

<br/>

## 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.

1. **Get an API key** — [sign in](https://api.hanzilla.co/dashboard) to your developer console, then create a key
2. **Pair a browser** — create a pairing token, send your user a pairing link (`/pair/{token}`) — they click it and auto-pair
3. **Run a task** — `POST /v1/tasks` with a task and browser session ID
4. **Get the result** — poll `GET /v1/tasks/:id` until complete, or use `runTask()` which blocks

```typescript
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](https://browse.hanzilla.co/docs.html#build-with-hanzi) · [Dashboard](https://api.hanzilla.co/dashboard) · [Sample integration](examples/partner-quickstart/)

<br/>

## 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 PNG. |

<br/>

## 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](mailto:hanzili0217@gmail.com?subject=Partner%20pricing) for volume pricing.

<br/>

## Development

**Prerequisites:** [Node.js 18+](https://nodejs.org/), [Docker Desktop](https://docs.docker.com/get-docker/) (must be running before `make fresh`).

### First time (local setup)

```bash
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

```bash
make dev
```

Starts the backend services (Postgres + migrations + API server) and ser

[truncated…]