qz Browser Agent
A local-first browser agent that runs in your own signed-in Chrome, bringing your own model to research, automate, and extract web data.
- Source repo
- alibaba/qz-browser-agent
- Stars
- ★ 228
- Last updated
- 7d ago
- License
- Apache-2.0
- Primary language
- HTML
- FA score
- 57/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformChatGPT · Codex · Claude Code · OpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Market and competitive researchers who need figures pulled from inconsistent third-party sites into a sourced comparison table.
- Not a fit if
- Teams that need a signed Firefox extension (not yet published)
- Server environments without a Chromium browser to attach to
- Website
- alibaba.github.io/qz-browser-agent ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-14latest release v0.1.9 (2026-11-14)+1.1 ★/day over 7 days
- Source review
- 57/100 · Major gaps
What does this agent do, and when should you use it?
qz is an Apache-2.0 open-source browser agent from Alibaba, shipped as a Chrome extension that lives in the side panel; you describe a task in one sentence and it works across the sites you are already signed in to. It is bring-your-own-model: presets cover DeepSeek, OpenAI, Claude, OpenRouter, Kimi For Coding, Fireworks AI and others, and a ChatGPT account can be used through OpenAI Codex sign-in without an API key. Data stays on your machine and goes only to the model you configure and the sites you visit. Beyond the extension, the qz-browser-agent npm package ships a CLI with session create, script, create and mcp commands, so coding agents such as Claude Code, Codex and pi can drive the browser directly or hand a whole web task to qz's built-in agent. Tasks can run in parallel with subtasks, and a successful run can be saved as a reusable Skill. Because it attaches to your real local Chrome or Edge, existing logins, cookies and extensions just work with no virtual environment to set up.
As a Chrome side-panel extension, qz reads and manipulates the pages you are already logged into: after you enter a prompt it clicks, scrolls and extracts content, then assembles results into data tables, local files or sourced reports. Runnable tasks can fan out in parallel with subtasks, and a working flow can be captured as a reusable Skill via "Save this as a Skill" so a single sentence reruns it later. For programmatic use, the qz-browser-agent npm package provides qz session create (opens a browser session without a model, emits qz_skills with --json), qz script (runs a JavaScript file against the qz SDK and prints {ok,result,trace}), qz create (hands the task to the built-in agent, with --stream for progress) and qz mcp (returns an HTTP URL for MCP clients). A separate Skill installed with npx skills add alibaba/qz-browser-agent -g serves as the direct-drive guide for external coding agents.
- Market and competitive researchers who need figures pulled from inconsistent third-party sites into a sourced comparison table.
- Developers using Claude Code, Codex or pi who want their agent to read and act on real signed-in pages instead of hitting login walls.
- Analysts running a recurring weekly digest: save a successful collection flow as a Skill and rerun it with one sentence.
- Researchers and students gathering papers, rankings or award lists into a linked table.
- Operations staff automating repeated page workflows inside their everyday browser, with the ability to step in or stop at any point.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
npm install --global qz-browser-agentnpx skills add alibaba/qz-browser-agent -gnpx qz-browser-agent@latest connect urinpx qz-browser-agent@latest
- Environment variables
SESSION_ID- Runtime
- Node.js 24
How do you install or deploy this agent?
Option 1: click "Add to Chrome" on the Chrome Web Store, then click the qz icon in the toolbar to open the side panel.
Option 2: without Web Store access, download the ZIP from the latest release, extract it, open chrome://extensions with Developer mode enabled, and use "Load unpacked" on the extracted qz-browser-agent-extension folder.
Building from source needs Node.js 24 LTS and npm:
npm ci
npm run buildThen load dist/extension/ at chrome://extensions. To use the CLI/MCP bridge from external agents you need Node.js 22 or later and the global package:
npm install --global qz-browser-agentOr install the direct-drive Skill:
npx skills add alibaba/qz-browser-agent -gHow do you use this agent?
Open the side panel, go to Settings, pick a provider (e.g. DeepSeek or Claude, or OpenAI Codex to sign in with a ChatGPT account), paste your API key and save. Then enter a task such as:
Find this year's Nobel Prize winners in every category and put them in a table with source links.To drive the browser from a coding agent, start a session and run scripts:
qz session create --title "Compare models" --json
qz script --session SESSION_ID task.js
qz create "your task" --streamFor MCP clients, run qz mcp and use the HTTP URL it returns. Without a global install, substitute npx qz-browser-agent@latest for qz. To pair a specific browser profile:
npx qz-browser-agent@latest connect uriWhat are this agent's strengths and limitations?
- Runs in the user's real, already-logged-in Chrome or Edge, so logins, cookies and extensions work without a virtual browser environment.
- Model-agnostic with presets for DeepSeek, OpenAI, Claude, OpenRouter, Kimi and Fireworks, plus a ChatGPT account path; data goes only to the configured model.
- Offers both a human-facing side panel and a CLI/MCP surface (session create, script, create, mcp) that Claude Code, Codex and pi can call.
- Supports parallel tasks with subtasks and lets a successful run be saved as a reusable Skill.
- Apache-2.0 licensed, with the extension and CLI free to use.
- Released packages target Chrome and Edge only; Firefox has no signed listing yet, just a development-only temporary load path.
- Results depend on the chosen provider supporting the required protocol and tool calling, and often require a paid API key or ChatGPT plan.
- The CLI/MCP path requires Node.js 22+ and source builds require Node.js 24 LTS, adding runtime version constraints.
- Local-first still means data is sent to the model provider you choose and to the sites you visit, so network and third-party APIs are dependencies.
How does this agent compare with similar options?
The README compares qz against Nanobrowser, Browser Use, agent-browser and Playwright MCP, claiming qz provides built-in support for delegating a whole task, running in your own logged-in Chrome, real-time step control for humans and agents, many parallel tasks with subtasks, and saving a run as a reusable Skill — while the others are partial or unsupported (Playwright MCP is listed as not supporting whole-task delegation or Skill saving). It also argues other browser agents are typically watch-only, hard to interrupt mid-task, and designed for either people or agents rather than both.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| qz Browser Agent This agent | 57 · Major gaps | Browser extensionFree + model costs | ★ 228 | 7d ago | HTML | ChatGPT · Codex · Claude Code · OpenAI API · Claude API |
| OpenCLI Browser Automation CLI | 61 · Some gaps | CLIFree | ★ 31k | 13d ago | JavaScript | Claude Code |
| Open Browser Use | 65 · Some gaps | CLIFree | ★ 430 | 18d ago | JavaScript | Codex · Claude Code |
| Lightpanda Browser | 67 · Some gaps | CLIFree | ★ 42k | 1d ago | Zig | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
permissions.md enumerates all 19 permissions with callers and separates optional grants (history/bookmarks/desktopCapture/downloads.open) from install-time ones, and a localized first-use disclosure gates task execution, so data_flow_transparency scores 3 and user_confirmation 2. However <all_urls>, debugger, scripting and geolocation are granted at install, so least_privilege is only 1; sensitive data handling documents local storage and deletion but credentials live in the browser profile and page/network content may carry auth data, scoring 2; dependencies are pinned with overrides but include GitHub and SheetJS CDN tarballs outside the registry, dependency_security 2; external effects (form submissions, downloads, MCP egress) lack a unified rollback/undo path, so external_effects and rollback are 1 each; attribution is supported by THIRD_PARTY_NOTICES and upstream-license preservation rules, scoring 2.
AGENTS.md specifies session isolation, serialized writes, terminal-state barriers, stable error codes and recovery guidance, and SKILL.md documents exit codes and sessionId passing, so self_consistency is 2; dependency availability is weakened by inconsistent Node requirements (README/SKILL say 22+, package.json engines and AGENTS.md say 24) and non-registry dependencies, scoring 1; failure messages are specified with stable codes and localized explanations but the sample shows only the convention, scoring 2.
README addresses both end users and coding agents with concrete scenarios, audience_and_scenarios 2; SKILL.md states the script sandbox lacks document/fs/process and defines tab ownership and read-only cross-session inspection, capability_boundaries 2; trigger conditions (when to read create-task.md, when to use qz create) are described but depend on the external qz skill guide, trigger_precision 2; Chrome/Edge support, partial Firefox support and packaging differences are documented, environment_fit 2.
README is well structured with store and manual install paths, FAQ and examples, so information_architecture, install_notes and examples_and_faq are 2 each; naming and commands are largely consistent across docs, naming_stability 2; known limitations appear only in scattered notes (Firefox differences, storage exhaustion), scoring 1; LICENSE is full Apache-2.0 matching package.json, license 3; no CHANGELOG or versioning policy is present, versioning_changelog 1; maintenance responsibility points only to the issue tracker and publisher identity is unverified, maintenance_responsibility 1.
Outputs land as tables, files and sourced reports with export and Data-table support, output_usability 2; the logged-in real-browser execution and parallel research offer differentiation from generic agents, marginal_value 2; cost requires a user-supplied model key or ChatGPT account plus a Node CLI and broad permissions, so cost_benefit is 1.
The README comparison table is dated 'as of October 2026, based on public docs' without verifiable links, claim_traceability 1; CI workflows and test directories exist but the sample shows no test results or third-party corroboration, cross_source_corroboration 1; docs mostly separate facts from guidance, but competitor capability judgments in the comparison table are inference presented without labeling, fact_inference_separation 1.
- The extension receives broad install-time permissions (<all_urls>, debugger, scripting, geolocation) and runs inside your logged-in browser, so tasks may touch sensitive account data.
- Dependencies include GitHub and SheetJS CDN tarballs outside the npm registry, weakening supply-chain auditability compared with registry-only dependencies.
- Node version requirements conflict across documents (22+ vs 24), which can break CLI connection.
- Competitor comparisons and 'local-first' claims in the README lack verifiable links and should be treated as marketing statements, not verified facts.
- Publisher identity is unverified; maintenance responsibility and update path point only to the issue tracker.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
This release makes it easier to work with tabs you already have open, brings element queries into line across browser tools and the qz SDK, and improves the reliability of model response parsing and CLI cancellation. Improvements - Tab listings now show the current session’s tabs and unclaimed tabs by default, with an ownership field for each tab. Listing and read-only inspection leave ownership unchanged. The first browser action, navigation, or page.evaluate() call on an unclaimed tab claims it for the session. Use scope: "all" to also see tabs owned by other sessions, which are a …View on GitHub ↗ -
Release notes excerpt
A release with direct browser driving for external agents, more flexible model connections, and more reliable page interactions. Improvements - External agents can now drive the browser directly through CLI and MCP, without starting the built-in agent. Create a session with qz session create, then run JavaScript with qz script and the qz SDK. Browser operations and results appear in the side panel. - External sessions can now discover and reuse user Skills, with availability determined by Skill settings and the sites visited during the task. …View on GitHub ↗ -
Release notes excerpt
A release with a Firefox developer preview, improved page tools, and more reliable conversations. Improvements - Added a Firefox developer preview for Firefox 154+, with a native sidebar and CLI and MCP connectivity. Temporary loading is supported; a signed Firefox listing is not available yet, and scheduled tasks remain disabled. See the [Firefox differences guide](https://github.com/alibaba/qz-browser-agent/blob/main/docs/firefox-differences.md) for browser-specific limitations. …View on GitHub ↗
FAQ
Is qz free to use?
Which models can I connect?
Does it work on Edge or Firefox?
Where does my data go?
How do external coding agents call it?
Is qz Browser Agent open source?
Is qz Browser Agent safe to use?
Is qz Browser Agent still maintained?
Who makes qz Browser Agent?
What is qz Browser Agent's official website?
Thanks — we use this to improve the page.