---
name: axbot
description: Control AXBOT, the AI browser on the user's iPhone, from this computer over the local Wi-Fi. List and manage all tabs and Spaces (including private tabs), open pages, read semantic snapshots, click, fill forms, press keys, scroll, take screenshots, run JavaScript, read console logs, manage userscripts, and hand control to the user for logins, captchas or payments. Use when the user asks you to do something in AXBOT or in their phone's browser, or when a task needs the websites the user is logged in to on the phone. Needs the address shown in AXBOT > Settings > Agent mode.
---

# AXBOT

Base address: `$AXBOT` — if that is not an http:// address, ask the user for the address shown in AXBOT > Settings >
Agent mode (it looks like `http://192.168.1.5:41234/<key>/`), and use it in its place, e.g. `export AXBOT=<address>`.
The address contains the key: keep it out of logs and files you share.

AXBOT is a browser on the user's iPhone. With Agent mode on, it accepts commands at this address while AXBOT is in the
foreground and the phone and this computer are on the same Wi-Fi. You can control all of AXBOT: every tab in every
Space (a group of tabs), private tabs (marked private), and the user's userscripts. The user sees a small "Agent 控制中"
capsule on the phone and can pause or stop you at any time. Parameters, results and errors: `$AXBOT/api.md`.

## Call tools

- **HTTP** (works with curl): `POST $AXBOT/tools/<tool>` with a JSON object of arguments (or no body). The `axbot_`
  prefix is optional. `GET $AXBOT/tools` lists the tools and their parameters.
  ```bash
  curl -s -X POST "$AXBOT/tools/tabs"
  curl -s -X POST "$AXBOT/tools/navigate" -d '{"url": "https://example.com"}'
  curl -s -X POST "$AXBOT/tools/snapshot"
  curl -s -X POST "$AXBOT/tools/click" -d '{"target": "@12"}'
  curl -s -X POST "$AXBOT/tools/screenshot" -o /tmp/shot.png
  ```
  Results are plain text (screenshots are PNG). Status 200 ok, 400 bad arguments, 404 unknown tool or a wrong
  address, 409 the user has taken over (wait and retry), 422 the tool failed (the body says why).
- **MCP**: Streamable HTTP server at `$AXBOT/mcp`, tools named `axbot_*`. Claude Code:
  `claude mcp add --transport http axbot $AXBOT/mcp`. Codex: `[mcp_servers.axbot]` with `url = "$AXBOT/mcp"` in
  `~/.codex/config.toml`. opencode: `"mcp": {"axbot": {"type": "remote", "url": "$AXBOT/mcp", "enabled": true}}`.
- **CDP** (scripts): a small subset of the Chrome DevTools Protocol; discovery at `$AXBOT/json/version` and
  `$AXBOT/json/list`. With chrome-remote-interface, connect to a `webSocketDebuggerUrl` from the list:
  `CDP({target: url, local: true})`. Puppeteer and Playwright do not work (they need the full protocol).

## Work loop

1. `axbot_tabs` lists every tab grouped by Space, with ids like `t3` and flags (`current`, `private`, `loading`,
   `not loaded`). Ids stay the same until AXBOT restarts; then list again.
2. `axbot_navigate` with a `url` opens a new tab in the current Space and waits for it to load; with `tab` and `url`
   it loads the page in that tab. Tools without `tab` act on the current tab. The tab a tool uses is brought to the
   front (the user sees it). Use `axbot_tab` to open (in any Space, or private), select, close or move tabs, and
   `axbot_space` to create, switch, rename or delete Spaces (the older name `axbot_sphere` and the `sphere` parameter still work). Creating a Space does not switch to it: to put new tabs there, pass
   `space` to `axbot_tab` with `action: "new"`, or switch to it first.
3. `axbot_snapshot` lists what is on screen: roles, names, values and states, with refs like `@12` on interactive
   elements and headings (`scope: "full"` for the whole page). Passwords show as `value="••••"`.
4. Act with `axbot_click`, `axbot_fill`, `axbot_press`, `axbot_scroll`, using a ref (preferred), a CSS selector, or
   `text=Visible text`; it must match exactly one element. Each action returns the url, title, whether the page
   navigated, new tabs, and page events. After the page changes, take a new snapshot: refs from an older page or
   another tab are rejected as stale.
5. Wait for a visible result with `axbot_wait` (url pattern, selector, text) rather than fixed delays. Use
   `axbot_screenshot` only when you need to see the page; a snapshot is cheaper and has the refs.

## Debug pages and userscripts

- `axbot_evaluate` runs JavaScript in the page (body of an async function; `return` a JSON value; `arg` is passed in).
- `axbot_console` reads the tab's console messages and uncaught errors captured while Agent mode is on; pass `after`
  (from the previous "next after") to get only new ones. Pages loaded before Agent mode was turned on need a reload.
- `axbot_scripts`: `list`, `install` (`source` text or an http(s) `url`; same @name and @namespace updates the script
  and keeps its stored values), `enable`, `disable`, `source` (read, or replace with `source`), `delete` (the user
  confirms on the phone). Changes apply when pages reload: reload the tab with `axbot_navigate` and `action: "reload"`.

## Hand over to the user

- Logins, captchas, two-factor codes, payments and anything the user should decide: call `axbot_handoff` with a short
  message (shown on the phone, e.g. "Please log in to GitHub, then tap 完成"). It waits until the user taps 完成 (Done);
  if it returns "not finished yet", call it again. You are not in control until the user taps Done.
- "The user has taken over AXBOT" (HTTP 409): the user paused you. Wait a little and retry; do not spam retries.
- "Agent mode was turned off on the phone", connection refused, or 404 for every path: AXBOT is in the background,
  Agent mode is off, the phone changed networks, or the user refreshed the key. Ask the user for the current address.

## Limits

- Clicks and key presses are synthetic DOM events (`isTrusted` is false). A few sites ignore them; then try
  `axbot_evaluate` or hand over to the user.
- While you are in control, `alert` dialogs on the tabs you use are accepted and `confirm` / `prompt` dialogs are
  dismissed (you see them as events); downloads, app links and camera or microphone requests there are blocked.
- Not available: file uploads and downloads, cross-origin iframe contents, network interception, bookmarks, history,
  settings, browsing data, accounts, deleting Spaces (axbot_space delete asks the user to confirm on the phone).
- Requests work only while AXBOT is in the foreground on the phone. The address uses plain HTTP on the local network.