Getting Started

Installing chrome-use is just three things: install the CLI with one command, add the Chrome extension and register the local bridge, and pull the agent skills into your project. It ships as prebuilt binaries via GitHub Releases—no npm, no token—so neither the publisher nor you has to log into any account. Once installed, run chrome-use doctor to self-check in one shot.

The extension icon opens a local agent side panel. On macOS, Linux and Windows it supports Codex, Claude Code, OpenCode and Pi, with a current-page tag, CLI model menus, agent-specific permissions and conversation deletion. Upgrade older Windows hosts for full panel capabilities; no administrator access is required. See Local agent side panel for controls and privacy.

Install the CLI in one line

Download the prebuilt binary for your platform from the latest GitHub Release to install chrome-use. This is the primary distribution channel—it doesn't go through npm and needs no token.

$ curl -fsSL https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.sh | sh

> irm https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.ps1 | iex

On Windows it installs to %LOCALAPPDATA%\Programs\chrome-use with no admin rights and adds that to your user PATH, keeping the existing entries exactly as they were, %USERPROFILE%-style variables included. The download's sha256 is checked and a mismatch installs nothing. To pin a version or location, set $env:AGENT_BROWSER_VERSION = 'v1.5.139' or $env:AGENT_BROWSER_BIN_DIR = 'D:\tools' first; set $env:AGENT_BROWSER_NO_PATH = 1 to leave PATH alone.

Other install methods

When you need a pinned version, a custom install directory, or manual placement on Windows:

# pin a specific version
$ curl -fsSL https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.sh | AGENT_BROWSER_VERSION=v1.5.188 sh

# install to a custom directory
$ curl -fsSL https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.sh | AGENT_BROWSER_BIN_DIR=$HOME/bin sh

• macOS app bundle: on a Mac the installer puts ChromeUse.app (signed and notarized) in <prefix>/share/chrome-use/ next to the bin directory, ~/.local/share/chrome-use/ by default, and chrome-use is a symlink into it. That way System Settings → Privacy & Security → Files and Folders lists chrome-use once, as "ChromeUse" with its icon, when an agent you run from the side panel works in a project under Documents, Desktop or Downloads. AGENT_BROWSER_NO_APP_BUNDLE=1 installs the bare binary instead.
• Windows: download chrome-use-win32-x64.tar.gz and its .sha256 from the Releases page, check that (Get-FileHash chrome-use-win32-x64.tar.gz -Algorithm SHA256).Hash matches the .sha256, extract with tar -xzf, and put chrome-use.exe on your PATH. Check the hash before running it: an interrupted download still extracts into an .exe, which then fails at launch with an access violation (0xC0000005) rather than saying the download was incomplete. The extension path for connecting to your real Chrome works on Windows too—see the next section.
• npm (legacy): npm install -g chrome-use is still published, but GitHub Releases is the primary channel now.

Install with Nix

Run directly from the repository flake, or import its Home Manager or NixOS module for a declarative installation:

# run once without installing
$ nix run github:leeguooooo/chrome-use -- --help

# flake input
inputs.chrome-use.url = "github:leeguooooo/chrome-use";

# Home Manager: install and register the native-messaging host on activation
imports = [ inputs.chrome-use.homeManagerModules.default ];
programs.chrome-use.enable = true;

# NixOS: install system-wide and optionally force-install the extension
imports = [ inputs.chrome-use.nixosModules.default ];
programs.chrome-use = {
  enable = true;
  forceInstallExtension = true;
};

The NixOS module writes the managed Chrome and Chromium extension policies. Native-messaging registration is per user; run chrome-use extension connect once after switching, or use the Home Manager module above.

For the list of pinnable tags, see Lineage—how the tags evolved from the agent-browser fork (early v0.x-fork.N tags) to today's chrome-use v1.5.x tags.

Install the extension, connect your real Chrome

To drive the real Chrome you're already logged into (reusing existing sessions, no confirmation prompts), install the browser extension and register the local bridge once. This is the recommended path.

On macOS/Linux, chrome-use extension install also registers the native host in existing custom data directories of running Chromium-family browsers started with --user-data-dir=<path>. For a browser that is not running or cannot be discovered, use chrome-use extension install --user-data-dir "/path/Chrome Data"; --user-data-dir=<path> is also accepted and the option may be repeated. Every explicit directory must already exist. The command lists written manifests and reads back their name and launcher path. This confirms registration only: reopen the side panel in that Chrome or wait for automatic reconnection. Windows uses HKCU registration and rejects this option. Discovery scans only the current user’s processes. Failures in discovered directories warn and skip that registration; default and explicit directory failures remain errors (retry with --user-data-dir). Successful custom registrations are recorded in ~/.chrome-use/custom-host-dirs.json for status and uninstall even when the browser is stopped. Recording failures warn that uninstall may leave manifests behind.

1. Install the chrome-use extension from the Chrome Web Store with a one-click Add to Chrome. The store build stays stable across restarts, which suits unattended use. Confirm you got the right one by the listing name chrome-use and extension ID knfcmbamhjmaonkfnjhldjedeobeafmk (its repo codename is ab-connect).
2. Register the native-messaging host—one time:

# register the local bridge (one time)
$ chrome-use extension install

# after that, open drives your already-logged-in Chrome directly
$ chrome-use open https://x.com/home

From then on, chrome-use open drives your real, already-logged-in Chrome through native messaging—no debug port, no token, and never an "Allow remote debugging?" prompt. The extension auto-updates and stays connected across restarts, so you never confirm again on later calls. For how the connection works, see Connecting to your real Chrome.

$ chrome-use extension install --no-profile      # never writes the policy profile
$ chrome-use extension install --all-profiles    # opens the Store page in each missing profile

$ profiles remove -identifier com.leeguoo.chrome-use.connect

The profile needs an open window

chrome-use puts its tabs into a profile that already has a window open, and never opens a window itself (that would bring Chrome up in front of you). With no window it stops with profile not open (code profile_not_open): open a window in that profile first, then rerun. If it cannot tell whether a window is open, it stops with profile window unavailable (profile_window_unavailable). Unknown means nothing is created, and neither error is retried automatically. The first-tab cleanup codes are covered in Troubleshooting.

Pull the agent skills

Install or refresh manually with chrome-use skills install; use chrome-use skills install --project for the current project. Restart your agent or reload its skills afterward. Global destinations cover ~/.agents/skills, Claude Code, Codex, Cursor, and existing Pi, OpenCode, Windsurf, CodeBuddy and Trae configurations. CLAUDE_CONFIG_DIR and XDG_CONFIG_HOME are respected. Project installs use .agents/skills and .claude/skills, plus existing .pi, .windsurf, .codebuddy and .trae configuration directories.

PowerShell also extracts the bundled skill from older CLI releases, bypassing their npx dependency. Explicit UTF-8 decoding preserves content on Windows PowerShell 5.1. Architecture detection also works when an agent omits the usual Windows environment variables. CLI JSON errors retain their details. A self-check timeout or failure is reported as an error. Windows Chrome detection does not launch the browser; doctor checks disk space, gives PowerShell environment-variable guidance, and omits macOS-only ChooseBrowser paths. Optional cloud keys need no setup; encryption keys are generated on first auth save. The Chrome Web Store extension still requires a one-time manual install. Installer completion does not verify its connection.

Claude Code — plugin marketplace (recommended): installs the skill globally (all projects), auto-updates, and lists the rest of the *-use family:

> /plugin marketplace add leeguooooo/plugins
> /plugin install chrome-use@leeguooooo-plugins

Runners outside the built-in mappings can still install the SKILL.md with skills.sh. This alternative needs Node and its own dependencies. Add -g for a global install (visible to every project); drop it to install only into the current project:

$ npx skills add leeguooooo/chrome-use -g

Codex users: Codex ships its own browser plugin and picks it for browser tasks. Measured on a machine with many skills installed, Codex also trims every skill description to a few characters or none, so the skill's description cannot win the routing, and naming chrome-use in the prompt was not enough either. What worked was one line in the project's AGENTS.md:

Use the `chrome-use` CLI from the shell for every browser task; start with `chrome-use skills get core`.
Do not use the built-in Chrome plugin for browser work here.

Either way the AI agent gets the right usage patterns and pre-authorized bash permissions for chrome-use; the specialized guides (electron / slack / agentcore / …) are served by the binary itself via chrome-use skills get <name>, so they always match the installed version. Once installed, it's worth reading The core loop first.

The installed discovery entry loads chrome-use skills get core once, then uses task-specific references as needed. If an old installed copy contains its own command manual without that handoff, refresh it with chrome-use skills update. Updating the binary alone does not replace that installed file.

To upgrade, run chrome-use upgrade: it installs the latest GitHub Release, then refreshes each installed copy of the skill it finds (Claude Code plugin, a git checkout, or the folders the installer writes). chrome-use upgrade --check or --json reports current and latest without changing anything; exit code 2 means the check failed. Other commands check for a newer release at most once a day, in the background, and while one exists print one line to stderr on each run; CHROME_USE_NO_UPDATE_CHECK=1 or USE_NO_UPDATE_CHECK=1 turns that off.

Run your first command

The browser stays running across commands, so the ones below feel like a single session. When you're done, wrap up with chrome-use close.

# take a screenshot of a page
$ chrome-use open https://example.com
$ chrome-use screenshot home.png
$ chrome-use close

For the full open → snapshot -i → fill → click walkthrough (search, click a result, screenshot again), read The core loop; for every command and flag, see Commands.

Diagnose install problems

When a command fails unexpectedly (Unknown command, Failed to connect, a stuck daemon, a version mismatch after upgrade, Chrome not found, and so on), run doctor before anything else.

# full diagnostic: environment, Chrome, daemon, config, providers, network, launch self-test
$ chrome-use doctor
$ chrome-use doctor --offline --quick   # fast, purely local
$ chrome-use doctor --fix               # run destructive fixes (reinstall Chrome, clear stale state…)
$ chrome-use doctor --json              # structured output for programmatic use

Every doctor run automatically cleans up stale socket / pid / version sidecar files; destructive operations only run when you add --fix. Exit codes: 0 when everything passes (warnings included), 1 on any failure.

The local agent side panel supports /skill selection, image attachments, conversation tool/model options and scheduled prompts in independent background sessions. See the side panel guide.

Source checkout: contributor hooks

The Git pre-push hook does not sync to ClawHub by default. Ordinary pushes do not require pnpm or ClawHub. Maintainers can opt in for one push with CHROME_USE_CLAWHUB_SYNC=1 git push. Only 1 enables sync; SKIP_CLAWHUB_SYNC=1 always takes precedence. Sync failures warn without blocking the push. Explicit pnpm run clawhub:sync publishing is unchanged. These variables control the source checkout's hook, not the installed CLI.

On Linux with Docker and a cached node:24-bookworm image, run sh scripts/test-pre-push-sandbox.sh to test the hook. The runner never pulls images or installs dependencies. It checks isolation before testing local Git pushes with a fake publisher in an unprivileged container with no network or host mounts, a read-only root, temporary storage and resource limits.