# Install axuse — instructions for the AI agent

The user asked you to install axuse: a tool from https://ax-use.com (source: https://github.com/ctoldigital/axuse) that lets you use the web browser and apps on their computer. Assume the user is not technical. Do the setup yourself and explain only the choices they need to make and what they need to click.

**Never ask the user to open a terminal or type commands.** If your sandbox blocks an authorized step (installing, writing your own settings, launching a browser), use your host's permission mechanism if available. Explain in one plain sentence what the user is approving. If local execution is unavailable, say so and give the relevant clickable installation route; do not claim you installed anything.

## 0. Choose the user's language

Talk to the user in their own language for the whole installation: every question, choice, explanation, click instruction, warning and status message. Do not default to English.

1. **Decide the language before your first message to the user.** Check, in this order, and stop at the first clear answer: (a) the language the user wrote their request in, if it is clearly not English; (b) the OS locale or UI language, read with local tools when you have local read access: on macOS `defaults read -g AppleLanguages` (first entry) or `locale`; on Windows `(Get-UICulture).Name` or `Get-WinUserLanguageList` in PowerShell; on Linux the `LC_ALL`, `LC_MESSAGES` or `LANG` environment variable. Read only the language setting, nothing else about the system.
2. The install sentence itself is in English, so an English message is not a language signal: if the user's request is in English, rely on the OS locale. If the two disagree because the user clearly wrote in another language, follow the language they wrote in. If local access is unavailable or the locale is unclear, fall back to English.
3. Translate everything you say, including the setup questions in step 1, the restart message in step 5 and the first-task suggestion. Keep these unchanged and untranslated: commands, file paths, URLs, environment variable names (`AXUSE_BROWSER`), tool names (`ax_open`) and the exact browser menu labels where the user's browser is in English. For labels that appear in the user's browser or OS (for example **Developer mode**, **Load unpacked**, **Accessibility**), give the label as it appears in their language when you know it, with the English label in parentheses.
4. Do not ask the user which language to use unless the signals above genuinely conflict. If the user later writes in a different language or asks to switch, switch immediately and stay in that language.
5. The first task to paste after restarting (step 5.4) should be translated into the user's language as well.

## 1. Identify the host and ask the setup questions

Determine the OS and the agent you are running in. Agent names alone do not prove local access: Codex, ChatGPT Work, Claude Work/Cowork, Claude Code, Antigravity (agy), OpenCode, Kiro, Cursor and other MCP hosts may have different installation and reload mechanisms.

**First discover the installed supported browsers and their profiles, then ask the user to choose.** This discovery is required when you have local read access; do not simply present a generic browser list and ask the user to find their own profiles.

- Detect the OS, then check its normal application locations, executable lookup and (on Windows) installed-app registry entries for Chrome, Edge, Chromium and Chrome for Testing, including installed variants. Record actual executable paths. Do not launch a fresh browser just to discover profiles.
- For each detected browser, inspect its user-data location for existing profiles. For Chrome, start with `~/Library/Application Support/Google/Chrome` on macOS, `%LOCALAPPDATA%\\Google\\Chrome\\User Data` on Windows, or `${XDG_CONFIG_HOME:-~/.config}/google-chrome` on Linux. Resolve these placeholders with the OS environment/local tools, not as literal path strings. Account for browser variants and custom user-data directories when discoverable from the selected running instance; do not assume all installations share the stable Chrome directory. Use the corresponding browser-specific location for Edge and Chromium.
- Read only profile metadata: parse `Local State` → `profile.info_cache` to map profile directory keys such as `Default` and `Profile 1` to their display names. Check the listed directories exist. If metadata is missing, list existing `Default`/`Profile *` directories as candidates and label unknown display names honestly. Do not create or change profiles during discovery, or read/display cookies, tokens, passwords or browsing history.
- Present the installed browser names and discovered profile display names as choices, using the directory key to distinguish duplicate names. If local access, permissions or metadata prevent discovery, explain the specific limitation and ask the user to identify the profile in the browser's profile menu. Do not pretend a scan succeeded.

**Before configuring axuse, ask the following and wait for the answers.** Reuse choices the user already explicitly provided, matching them to the discovered browser/profile where possible.

1. **Browser and instance:** “Which browser should axuse use: Google Chrome, Microsoft Edge, Chromium, or Chrome for Testing? If you have multiple versions or windows, which one?” Offer the supported browsers actually installed. Safari and Firefox are not supported by the browser backend. Do not silently choose Chrome or install another browser.
2. **Default profile:** Offer the profiles discovered in the selected browser and ask: “Which of these profiles should axuse use by default? Or would you prefer a separate profile for axuse?” Explain: “Your profile holds your signed-in sessions for sites such as Airbnb and Google. Choosing your existing profile lets axuse use those logins; a separate profile starts signed out.” Ask even if only one profile is found. Do not assume the browser's folder named `Default` is the user's intended profile. Record the chosen display name and directory key for future setup and verification.
3. **Extension, when Chrome is chosen:** “Would you like to install the axuse Chrome extension so I can use your existing browser profile and signed-in websites?” Recommend it for an existing profile. Offer the same bridge option for Edge. Explain that a separate browser can run without the extension, but it does not automatically inherit existing logins. The axuse browser extension is separate from the Claude `.mcpb` desktop extension.
4. **Optional desktop control:** “Do you want axuse to control other desktop apps too, or only websites?” Explain that macOS desktop control needs Accessibility and Screen Recording permissions. Keep desktop control off unless requested.

If the user wants their existing logged-in profile but declines the extension, explain the limitation and agree on a separate profile or an explicitly configured developer connection before continuing. Do not substitute a signed-out browser and call that the selected profile.

## 2. Install and register with the current agent

### A. Claude desktop app / Cowork: the one-click file

1. Download https://ax-use.com/download/axuse.mcpb into Downloads and open it using your local tools, or give the user that clickable download if local tools are unavailable. Ask them to double-click the file and click **Install** in Claude.
2. Claude includes the Node runtime; do not install Node.js or edit unrelated config files. Set the selected browser in the extension's browser setting if available. Enable “Allow control of other Mac apps” only if desktop control was requested.
3. Continue with browser/profile setup below. If tools become available only after restart, give the user the restart handoff in step 5 first and resume the remaining setup afterward. Do not treat installing the `.mcpb` as completing browser-extension setup.

### B. Other agents with local command access

1. Check `node -v`. If Node.js is missing or older than v22, explain and obtain approval to install a supported Node.js LTS release: Mac `brew install node` if Homebrew exists, otherwise https://nodejs.org; Windows `winget install OpenJS.NodeJS.LTS`. On Linux, use the official Node.js installation instructions for the distribution. Do not ask the user to type commands.
2. Use a permanent folder: `~/.axuse/app` on Mac or Linux, `%LOCALAPPDATA%\axuse\app` on Windows. Clone https://github.com/ctoldigital/axuse.git there, or download and unzip https://github.com/ctoldigital/axuse/archive/refs/heads/main.zip and put its contents there. Reuse an existing installation; inspect local changes before updating it and never overwrite them.
3. Run `node <folder>/src/cli.js doctor` with `AXUSE_BROWSER` set to the selected browser's absolute executable path. If that browser is missing, ask whether to install it or select another supported browser. A sandbox startup failure is not proof the browser is missing: use the host's permission mechanism where available, or report that verification is pending.
4. Register axuse with the current agent, using the absolute path to `<folder>/src/cli.js`:
   - Codex: `codex mcp add axuse -- node <folder>/src/cli.js mcp`
   - Claude Code: `claude mcp add --scope user axuse -- node <folder>/src/cli.js mcp`
   - OpenCode: merge the block from `node <folder>/src/cli.js print-config --harness opencode` into its `opencode.json`.
   - Antigravity / agy: use the block from `print-config --harness agy` in its MCP settings.
   - ChatGPT Work, Claude Work, Kiro, Cursor or another MCP host: inspect the host's supported local MCP setup and use `print-config --harness generic` where it accepts a standard `mcpServers` block. Do not invent config locations or assume every chat surface supports local MCP.
   Change only the axuse entry. Preserve unrelated settings. Add `AXUSE_BROWSER` to the MCP server environment for the selected executable; also add `AXUSE_ENABLE_MACOS_CUA=1` on macOS only if desktop control was requested. Follow the host's environment syntax; printing a config block alone does not register the server.

### C. A chat without local installation access

Say you cannot install apps on the user's computer from this chat. For Claude desktop, give the https://ax-use.com/download/axuse.mcpb link and the double-click → Install steps. Otherwise direct the user to a locally running MCP-capable agent, such as the Codex app or Claude Code, and have them paste “Install axuse by following https://ax-use.com/install.md” there. Include their chosen browser/profile/extension preferences in the handoff. Do not claim that the current chat is connected.

## 3. Connect the chosen browser and profile

### If the user chose the browser extension

1. Use the permanent installation from step 2B, or locate the installed Claude bundle's `server` folder (it contains `src/cli.js` and `bridge/extension`). Do not guess a bundle path. If you cannot access it, finish this step from a local agent with command access.
2. Run `node <folder>/src/cli.js setup --browser chrome` (use `edge`, `chromium` or `chrome-for-testing` for the selected supported instance). This registers the native messaging host and prints the exact extension folder. For a browser variant, use its supported setup identifier; do not register a different browser's host.
3. Ask the user to switch to the **chosen browser profile**, using the browser's profile menu. Setup may open a window in a different profile, so verify this rather than assuming it selected the right one.
4. In that profile, open `chrome://extensions` for Chrome or `edge://extensions` for Edge. Turn on **Developer mode**, click **Load unpacked**, and select the exact `bridge/extension` folder printed by setup. For Chromium or Chrome for Testing, use `chrome://extensions`. You can open the page and folder for the user; explain the clicks they must perform. Keep the extension folder in place after installation.
5. Explain that the extension can control browser tabs and use signed-in sessions; the browser may show a debugging notice while axuse works. Let the user review any extension permission prompt. If organization policy blocks Developer mode, report that and ask whether to use a separate profile or have their administrator enable the extension.
6. **Connect only the selected profile:** the bridge currently has one active extension connection, not a browser/profile selector. If axuse is enabled in other running browsers or profiles, ask the user to disable it there before verifying. Do not close unrelated windows or claim that a profile is pinned by a setting.
7. Run `node <folder>/src/cli.js bridge verify`. Then use `ax_open` with `backend: "extension"` for the test in step 5 and future browser tasks (including `ax_open_many` when appropriate). `AXUSE_BROWSER` alone does not select the extension backend or its profile. Confirm the test tab appears in the browser/profile the user chose.

### If the user chose a separate profile without the extension

Use the selected browser executable and a new dedicated persistent user-data directory, for example `~/.axuse/profiles/personal` on Mac/Linux or `%LOCALAPPDATA%\axuse\profiles\personal` on Windows. Call `ax_open` with `backend: "cdp"`, `executable_path` and `profile_dir` set to those absolute paths. Reuse that directory for future tasks so logins made there persist. The user signs in themselves when needed.

Do not point `profile_dir` at the user's daily Chrome/Edge data directory, copy auth files, or close their browser to seize its profile. `profile_dir` is a user-data directory, not a display name or a `Default`/`Profile 1` subfolder. `AXUSE_PROFILE_DIR` only controls the location of temporary profiles; it does not select a persistent signed-in profile. If the user explicitly wants a temporary signed-out session, omit `profile_dir` and explain that its logins will not persist.

## 4. Check OS and host permissions

- **Browser-only setup:** allow the agent's MCP server/local process to run through its normal permission controls, and complete the extension clicks if selected. Browser automation through CDP/the extension does not by itself require macOS Accessibility or Screen Recording.
- **macOS desktop control, if requested:** enable `AXUSE_ENABLE_MACOS_CUA=1` in the MCP environment (or Claude's desktop-control setting). Guide the user to **System Settings → Privacy & Security → Accessibility** and **Screen Recording** (called **Screen & System Audio Recording** on some versions). Enable the app or executable macOS identifies as running axuse, which may be the agent app, terminal or Node host. Use the actual prompt/diagnostic to identify it. With the user's permission, `node <folder>/src/cli.js doctor --request-tcc` in the same environment can request the grants; ordinary `doctor` checks them. macOS may require quitting and reopening the affected app after a grant. Recheck from the actual MCP host; a successful terminal check alone does not prove that host has permission.
- **Windows:** allow the selected host/browser through any actual security prompt or organization policy; desktop control cannot interact with elevated windows from a normal process. Do not request administrator rights for ordinary browser setup.
- **Linux:** browser tools work; desktop control is not implemented. Explain this if desktop control was requested.

Report any denied or policy-managed permission with the specific blocked feature and next click. Do not claim it was granted or disable OS security controls.

## 5. Save the choices, restart, and verify

1. Save the agreed defaults in the agent's supported persistent instructions or memory, so they survive restart: browser/instance and executable path, profile display name, extension vs CDP, dedicated `profile_dir` if applicable, desktop-control choice, and any unfinished steps. For the extension, record the selected profile and the need to keep other bridge instances disabled; there is no automatic profile pinning. Do not store auth tokens. If persistent memory is unavailable, give the user a short handoff to paste into the next chat.
2. **Explicitly tell the user:** “Fully quit and reopen your agent app, or restart its CLI session, so it loads axuse. Most agents need a restart after adding an MCP server. If your app offers an MCP reload, you can try that first; if the tools still do not appear, restart the app and start a new chat.” Name the current app. This applies to Codex, ChatGPT Work, Claude Work/Cowork, Claude Code, Antigravity/agy, OpenCode, Kiro and other hosts that support this installation. A new chat alone may not reload the MCP configuration.
3. If a restart is required, report “Installed; verification pending after restart,” provide the saved choices and next action, and resume verification once the tools load. If tools are already available, test immediately. Open https://example.com **using axuse and the chosen backend/profile**, read its title, and confirm the visible browser/profile with the user. A doctor smoke test in a fresh browser or a successful bridge connection alone is not enough. Only report setup complete after this test works in the intended profile.
4. Give the user this concrete first task to paste after restarting:

   > Use axuse to visit google.com and find the latest stock price of Apple (AAPL). Include the currency, the quote's timestamp, and the source link.

5. Summarize the browser, default profile, extension choice, permissions and verification result in plain language. Use these saved defaults for future browser requests. Ask before submitting a form, buying, sending, publishing or deleting anything.

## Rules

- Don't use sudo or admin rights without asking. Don't change unrelated settings.
- Never silently replace the user's browser/profile choices with auto-detected defaults.
- If a step fails, say what happened and what the user can click or approve. Never hand the user terminal commands. Help: dev@ax-use.com.