# Install axdroid (Android phone) — instructions for the AI agent The user asked you to connect their **Android phone** so you can use it: axdroid from https://ax-use.com/phone-use/ (source: https://github.com/ctoldigital/axuse, folder `phone-use/android`). axdroid is a small app on the phone that lets you read its screen as text and tap, type and scroll. It reads text, and takes a screenshot only for a screen with no readable text (the phone's owner can switch that off in the app). It is free. Your job is to make this feel effortless. **The user does only two things: plug in the phone and tap “Allow” on it.** You do everything else. ## How to talk to the user (important) - **One step at a time.** Never show a list of steps. Say what you are doing now, or give ONE thing for the user to do. - **Two short sentences at most** per message. Plain words. No jargon: say “plug your phone in”, not “connect via ADB”. Never say “terminal”, “command”, “adb”, “developer options” unless the user has to tap exactly that (then name it once, in bold). - **Show progress**: start each message with a small counter such as “Step 2 of 4”. The four steps are: 1 Plug in · 2 Install · 3 Connect · 4 Try it. - When the user has to act, say exactly what they will **see** on the phone, then wait. Ask them to reply “done”. Do not do anything else until they do. - Celebrate each finished step in three words (“Got it.”, “Perfect.”). Never apologise at length. If something fails, say what happened in one sentence and what you will try next. Do not make the user debug anything. - Speak the user’s language (use the language rule in https://ax-use.com/install.md, section 0). Keep URLs, tool names and the exact on-screen labels of the phone in the phone’s language. - **Never ask the user to type a command.** Ask before installing anything on their computer, in one plain sentence. ## 0. Check you can do this You need to run local commands on the user’s computer and register an MCP server with your own app. - If you can: go on. - If you cannot (a plain chat window): say so in one sentence and give the user this to paste into a local agent app (Codex app, Claude Code, Cursor, OpenCode): “Install axdroid by following https://ax-use.com/install-phone.md”. Do not claim you connected anything. ## 1. Step 1 of 4: Plug in 1. **Get the helper tool.** Run `adb version`. If it is missing, ask once (“I need a small Google tool to talk to your phone. OK to install it?”) and install Android platform-tools: - macOS: `brew install android-platform-tools` if Homebrew exists; otherwise download https://dl.google.com/android/repository/platform-tools-latest-darwin.zip and unzip it to `~/.axuse/platform-tools`. - Windows: `winget install Google.PlatformTools`; if winget is missing, download https://dl.google.com/android/repository/platform-tools-latest-windows.zip and unzip it to `%LOCALAPPDATA%\axuse\platform-tools`. - Linux: your package manager’s `android-tools`/`adb`, or https://dl.google.com/android/repository/platform-tools-latest-linux.zip to `~/.axuse/platform-tools`. Use the full path to `adb` if it is not on PATH. 2. Say: “**Step 1 of 4.** Unlock your phone and plug it into this computer with a USB cable. Tell me ‘done’.” (A cable that only charges will not work: if nothing shows up, suggest another cable.) 3. Run `adb devices`. - **One device, state `device`:** go to step 2. - **State `unauthorized`:** say “Look at your phone. Tap **Allow** on the ‘Allow USB debugging?’ box. Tick ‘Always allow’ first.” Wait for “done”, re-check. - **No device listed:** USB debugging is probably off. Give these as ONE action at a time, waiting for “done” after each (ask the user for the phone’s brand only if the standard path does not match): a. “Open **Settings → About phone** and tap **Build number** seven times.” (On Samsung: **About phone → Software information → Build number**.) b. “Go back to Settings, open **System → Developer options** (Samsung: it is near the bottom of Settings) and turn on **USB debugging**.” c. “Unplug and plug the cable back in, then tap **Allow** on the phone.” - **Several devices:** ask which one, by model name (`adb -s shell getprop ro.product.model`), and use `-s ` from then on. - The phone must stay unlocked during setup. ## 2. Step 2 of 4: Install 1. Say: “**Step 2 of 4.** Installing the axdroid app on your phone. This takes a few seconds.” 2. Download https://ax-use.com/download/axdroid.apk to a temporary folder and run `adb install -r `. Confirm with `adb shell pm list packages com.axuse.axdroid`. - If install is refused (for example a “Install via USB” prompt on some Xiaomi/Oppo/Vivo phones): say “Tap **Install** on your phone” and wait for “done”. If the phone blocks it with a setting such as **Install via USB**, tell the user the exact switch to turn on, one at a time. 3. **Turn it on yourself.** Run: `adb shell settings put secure enabled_accessibility_services com.axuse.axdroid/com.axuse.axdroid.AxService` and `adb shell settings put secure accessibility_enabled 1`. Check with `adb shell settings get secure enabled_accessibility_services` (it must contain `com.axuse.axdroid`). - If the phone refuses (some makers block it), say: “Almost there. On your phone open **Settings → Accessibility → Installed apps** (or **Downloaded apps**), tap **axdroid**, turn it **On** and tap **Allow**.” You can open the page for them with `adb shell am start -a android.settings.ACCESSIBILITY_SETTINGS`. Wait for “done” and re-check. - Explain once, in one sentence, why this permission is needed: “axdroid uses Android’s accessibility feature (the one screen readers use) to read and operate the screen.” ## 3. Step 3 of 4: Connect 1. Say: “**Step 3 of 4.** Connecting your phone to me.” 2. Run `adb forward tcp:8360 tcp:8360`. The phone’s own server is then at `http://127.0.0.1:8360/mcp`. 3. Register that URL as an HTTP (streamable) MCP server named `axdroid`, the same way you add any MCP server to your own host (its command or settings file). Change only the axdroid entry and keep other settings. Do not invent config locations. - If your host can only run local stdio servers, say the phone connection is not available there yet and suggest an agent app that supports HTTP MCP. Do not claim it works. 4. Save to your persistent notes, if you have any: “axdroid: phone connected over USB; before each phone task run `adb forward tcp:8360 tcp:8360`.” Do not store secrets. 5. Tell the user, in the app’s own words: “Fully quit and reopen this app (or start a new session) so it loads the phone. Then ask me anything about your phone.” Name the app. ## 4. Step 4 of 4: Try it After the restart (or immediately, if the tools are already available), run `adb forward tcp:8360 tcp:8360` again and test with the phone tools: go to the home screen, open **Settings**, and read the Android version. - Success: say “**Done.** I can see and use your phone.” Then offer ONE example the user can paste: *“On my phone, open Clock and set an alarm for 7:00 tomorrow.”* - Failure: say what you saw in one sentence. Check in this order, fixing silently where you can: phone still unlocked and plugged in; `adb devices` shows `device`; accessibility is on for axdroid; `adb forward` is set. Only then ask the user to do one thing. ## Rules - Before the agent sends a message, makes a call, posts, pays or deletes something on the phone, ask the user first. The phone holds their private data. - A screenshot is possible only for a screen with no readable text, and never of a secure window. If the user asks, tell them they can switch it off in the axdroid app. - axdroid works on the phone and your computer. The screen text you read goes to your AI provider like any other conversation, and nothing is sent to ax-use.com. - Never change the phone’s other settings, never uninstall the user’s apps, and never use the phone’s lock-screen PIN or passwords. - If you are stuck, say so plainly and point to dev@ax-use.com. Never hand the user terminal commands. - Wireless use (without USB) and iPhone (axphone) are not part of this guide: iPhone is coming soon; say so only if asked.