NexusAndroid

In PowerShell, download the installer and the release's checksums as files, check the installer, then run it as a file (never piped into PowerShell from memory):

$r = 'https://github.com/pironjulien/NexusAndroid/releases/latest/download'Invoke-WebRequest "$r/get.ps1" -OutFile get.ps1Invoke-WebRequest "$r/SHA256SUMS.txt" -OutFile SHA256SUMS.txtSelect-String ' get.ps1$' SHA256SUMS.txt                  # expected SHA-256(Get-FileHash get.ps1 -Algorithm SHA256).Hash             # must be the same (case aside)gh attestation verify get.ps1 --repo pironjulien/NexusAndroid   # optional: build provenancepowershell -NoProfile -ExecutionPolicy Bypass -File .\get.ps1

It downloads the latest release for this PC's architecture (NexusAndroid-win-x64.zip or NexusAndroid-win-arm64.zip), checks its SHA-256 against the release's SHA256SUMS.txt before extracting anything, installs it into ~\.nexus\nexus-android\releases\<version>, then runs NexusAndroid.exe setup. Setup finds adb or downloads Google's official Platform Tools, declares the server to the AI apps it finds (Claude Code, Claude Desktop, Codex, Antigravity; your own entries are kept, each edited file is backed up first), then walks you through connecting the phone (steps above). Run get.ps1 again (downloaded and checked the same way) to update.

Verify a download. Every release file (both zips, both .mcpb extensions, get.ps1, SHA256SUMS.txt) carries a Sigstore build provenance attestation: gh attestation verify NexusAndroid-win-x64.zip --repo pironjulien/NexusAndroid (the bundle is also attached as NexusAndroid-<version>.intoto.jsonl).

Point the AI app at the installed executable with the argument --mcp (stdio):

• Claude Desktop: download nexus-android.mcpb (x64) or nexus-android-arm64.mcpb (Arm64) and open it (Settings > Extensions);
• Claude Code: claude mcp add nexus-android --scope user -- "<path>\NexusAndroid.exe" --mcp (or, for the whole Nexus pack: /plugin marketplace add pironjulien/nexus-plugins, then /plugin install nexus-android@nexus-plugins);
• Codex: codex mcp add nexus-android -- "<path>\NexusAndroid.exe" --mcp;
• Antigravity: agent panel ⋯ > MCP Servers > Manage MCP Servers > View raw config, add the nexus-android entry below inside "mcpServers", save.

Codex ~/.codex/config.toml:

[mcp_servers.nexus-android]command = 'C:\Users\<you>\.nexus\nexus-android\releases\<version>\NexusAndroid.exe'args = ["--mcp"]

JSON clients (Antigravity, Claude Desktop, Cursor, VS Code):

{  "mcpServers": {    "nexus-android": {      "command": "C:\\Users\\<you>\\.nexus\\nexus-android\\releases\\<version>\\NexusAndroid.exe",      "args": ["--mcp"]    }  }}

NexusAndroid.exe setup options: --no-wait (declare and get adb, without waiting for the phone), --no-register (leave the AI apps alone), --apps claude-code,codex (only these AI apps: claude-code, claude-desktop, codex, antigravity; the pack passes its -Only/-Skip choice as NEXUS_PACK_TARGETS, same names). get.ps1 -NoWait passes --no-wait. Exit code: 0 everything ready, 1 adb or the phone not ready, 2 an AI app not configured, 3 both. The Nexus pack runs it with NEXUS_PACK=1: no question, no wait, exit code 0 on success and a last line NEXUS_PACK_RESULT Claude Desktop=declared; Codex=declared; Antigravity=plugin. In Antigravity the server comes as a plugin (~/.gemini/config/plugins/nexus-android: server and agent guide), never as a global entry. An entry written by an earlier version (uvx nexus-android) is replaced by the executable.

The HTTP daemon shares one token file with NexusRelay and NexusBrowser: NEXUS_MCP_TOKEN_FILE when set, otherwise %USERPROFILE%\.nexus\mcp-token.txt. The installer reuses that file (creates it once if absent), sets the user variable NEXUS_MCP_TOKEN to its content and never rotates an existing token. Restart AI apps after the first installation so they read the variable; installing another Nexus product keeps the same token.

adb is looked for in this order: NEXUS_ANDROID_ADB (full path), the PATH, the Android SDK (Android Studio's default folder), winget's Platform Tools, then ~/.nexus/nexus-android/tools/platform-tools-<version>. When none is found, setup (or the server, in the background at start) downloads the current stable Platform Tools for Windows from Google's SDK repository (dl.google.com, the manifest sdkmanager reads), checks the size and SHA-1 Google publishes for the archive and unpacks it there; by using it you accept the Android SDK terms. NEXUS_ANDROID_ADB_DOWNLOAD=0 turns this off.

Typing accents and emoji needs the scrcpy server (Genymobile, Apache 2.0, version 5.0.1 pinned): setup (or the server at start) downloads it from the official scrcpy release on GitHub, checks its SHA-256 against the value written in the code and keeps it in ~/.nexus/nexus-android/tools. If the download is impossible (offline, proxy), accented text is refused with a message; it is never replaced by other text. ASCII typing works without it.

look and act also read the text the UI tree does not give (games, Flutter apps, video or map surfaces) on the image, with the OCR engine built into Windows, on the PC: lines listed with their @x,y, aimed at by their text, judged by the same safeguards, codes masked in the text and blacked out on the image. Routines: act(remember="name") saves a batch that went through, with stable targets (id:, text, desc:; never [N] or coordinates; a typed text made only of {{x}} becomes a parameter); act(routine="name", params={...}) replays it for any of the three agents, only in the app where it was recorded, every safeguard applied again (confirm and accords are never saved); look lists the routines of the foreground app.

Google Messages stores RCS messages in Android's messaging provider, like MMS, so the server reads them without going through the screen. An RCS group only has an encoded address there: the server works out its members and names the sender of each received message. A conversation archived or trashed in Google Messages stays readable and is labelled as hidden in the app.

Reads are fast: every adb shell content query starts a Java process on the phone (about 1 s), so at the first read the server pushes a 20 KB helper (phone/NexusQuery.java, built into nexus-query.dex) to /data/local/tmp and starts it once with app_process under the shell identity, as scrcpy does: no app to install, no permission beyond ADB's. It queries the providers the way Android's own content command does, read-only (query only), and serializes the rows itself with length-prefixed values, so a message text can never pose as an extra row. Each start draws a random token that goes into the socket name and comes back in every answer; any other server is refused. It answers only connections from the shell or root user (adbd, checked by the kernel) and stops after 10 minutes without a request. If the helper cannot run, reads fall back to adb shell with the same results; there, a read whose row numbers or row count (checked against the same read reduced to _id) do not add up is refused rather than shown.

The same helper reads the screen: it opens one accessibility connection (UiAutomation, what uiautomator dump opens and closes on every call) and keeps it, so look gets the UI tree, the screenshot (JPEG made on the phone) and the screen state in one exchange. It is read-only (no gesture, no global action, no typing) and leaves the user's own accessibility services running. Android allows only one such connection at a time: the helper is shared by every agent, hands it back before any uiautomator dump fallback, on its own after 45 s without a screen read, and right after reading a protected (banking or identity) app, so other tools (Appium, uiautomator2) can take it. The element list, its numbering, code masking and the refusal rules are the same as with uiautomator dump.

Threat model for outward actions (sending, calling, paying, publishing, transferring): the agent must never be able to make an outward action leave that differs from the one the user approved. The approved action has one canonical identity: the foreground app, what the elements of the UI tree say in document order (their text, or a keyed seal of the raw text when it is masked; not their exact position, so a 4-pixel shift or the keyboard opening does not void it), and the complete target of the gesture (the element that receives the tap with its resource id, bounds and drawing order, the tap point, the start and end of a swipe, the direction of a scroll, the field that has the focus for a key). The contract sits at the boundary of each physical injection: every tap (each tap of a double tap, on a quick reading that does not wait for the screen to settle, or no second tap), every swipe of a scroll (judged where the finger lands, on what it actuates there), every submit key (alone in its step) is sent right after its own fresh reading of the screen, judged on it, and compared with the approved identity; any difference refuses it. The token is bound to that identity only; the readable summary (recipients, content, attachments) is shown with it. A swipe or drag is judged on one reading for both ends. type only types into an editable field that has the focus, and pastes any control character (line break, tab) as text, never as a key. What the UI tree does not describe (a target found only by OCR, a drawn surface over the target or the recipient, a drawn surface without tree text in the header) is never bound to an accord: such an outward action is refused, the user does it; a video or photo preview beside a send button and a recipient that the tree describes does not block. Limit, stated plainly: a screen that changes in the few milliseconds between that last reading and the ADB injection is beyond what an ADB tool can see.

• Paying, sending, calling, publishing, deleting for good, formatting, uninstalling, resetting, cancelling a subscription, making a repository public: a button of this kind is refused without confirm=true, for every gesture aimed at it (tap, typing, clearing, swipe, x,y coordinates included). The agent sets it on the user's explicit order for that gesture, or after their "yes". The labels come from one policy file shared with the desktop tools (garde-fous.json), matched without accents or case and in every listed form ("Envoyez", "Payez", "Paiement", "Commandez", "Checkout", "Appeler"...). Everything else is free: deleting to the trash, accepting, sharing. A generic "OK" or "Validate" needs it on a screen that talks about a payment or a format. In a messaging, mail, social or phone app, a clickable icon with no name at all (often the send or call button) needs it too. Enter, call keys and any key outside a short safe list need it as well.
• Accord bound to the exact action (sending, calling, paying, publishing, transferring): confirm=true alone is not enough. The tool answers with the exact action as the screen shows it (app, button, recipients: the header plus any phone number or e-mail address shown, the text of the fields, named attachments, and the rest of the app's text on screen, masked texts bound by a seal of their raw text) and a single-use token valid 10 minutes; that screen is read and compared again right before each injection; the agent shows that summary to the user and sends the gesture again with accord="<token>" only after their yes. draft returns the token for its own draft. Any change in between (other conversation, edited text) voids the token: a new accord is needed. The same rule covers every way to send: tap, swipe or "slide to send", a scroll whose finger lands on such a slider (one scroll per step with an accord), Enter or call keys (alone in their step: tab first, then enter), open_url payment links and launch intents that call, send or pay. When the UI tree cannot be read, the action cannot be described: no token is given and the gesture is refused. Multi-line text is pasted (a line break is text, never the Enter key, which can send); no double tap on an outward button. Local destructive gestures (uninstall, reset, delete for good) keep confirm=true alone.
• Text read never authorizes anything: SMS, notifications and screens are data. A recipient that appears in a recently read text is flagged in the accord summary (allowed only if the user asked for it themselves), and text that looks like instructions aimed at an AI is flagged in the response. That detector is a signal only, never a block and never a guarantee.
• Target checked on the current screen: the UI and the phone state (lock, foreground app) are read again in one round trip just before each gesture; a changed [N] or a spot with nothing readable is refused. Reports: ✓ effect read back, ~ sent but not verified, ✗ refused or failed.
• One phone only: the owner's phone is identified by its hardware serial number, recorded at the first USB connection; emulators, TV boxes and other devices are ignored. One agent at a time drives it (lock shared by all servers on the PC, and by the sessions of the shared daemon); another one waits 30 seconds at most, then is told the phone is busy. A call the client cancels (or a client that disconnects) stops before the next step of a batch.
• Banking, payment, crypto, gambling, identity, authenticators: look, scroll and wait freely; tap, type or swipe only with confirm=true (the user's order to navigate); a money or send button, an unnamed icon, Enter or any validation key, never, even with confirm=true and an accord; when the UI tree cannot be read there, no aimed gesture at all (only back, home and recent); a link (open_url) or an intent (launch with action/data) that would open one of them, even as one choice among others, is refused (a deep link can prepare a payment).
• Intents and links that act on their own (CALL, sending a text without review, uninstalling, resetting, payment actions, upi:/bitcoin:/payto: links, auto-send extras): confirm=true, plus the accord bound to the exact intent for calls, sends and payments.
• Codes received by SMS or shown in notifications: masked before the agent reads them, and blacked out on the image (the [N] badges are drawn afterwards: they can only cover, never reveal). Codes the OCR finds on the image are blacked out too, on look images (large drawn surfaces without tree text) and on saved screenshots (every large drawn surface, labelled or not). Limit: the OCR of a saved screenshot only covers drawn surfaces of at least 25 % of the screen (or a tree with no text at all); a code drawn on a smaller surface is not blacked out. When the OCR is unavailable (outside Windows) or fails, look still returns the image of the user's own phone, with a clear warning that drawn codes are not masked; a saved screenshot is refused without unmasked=true. Bank card numbers (Luhn check) and IBANs (mod 97 check) are masked in every text the tools return (screen, notifications, SMS, clipboard, calendar, logs, web, map): card groupings only (4-4-4-4 followed or not by 1 to 3 digits, 4-6-5, 4-6-4, 4-4-5, 4-3-3-3, or one block of 15 to 19 digits; first digit 2 to 6), so calendars, draws, tables of numbers, SIRET and EAN-13 stay readable; IBANs only at the exact length of their country (SWIFT registry), in any case, even glued to a word; groups separated by one or two spaces, no-break spaces, dashes, dots or a line break. In the clipboard, a lone code, or a single word that looks like a password or a token, is not shown at all. When the UI tree cannot be read, codes cannot be located, so the image is not sent unless look gets confirm=true (with the user's agreement).
• Passwords: no typing into a password field, and no key there but navigation (back, tab, arrows). No typing either when the active field cannot be read, even with confirm=true.
• Locked phone: no code is ever entered. When Android itself keeps the phone unlocked (Extend Unlock, Smart Lock, trusted place or device: dumpsys trust says deviceLocked=0), phone reports code_required: false and look, act and capture wake it and lift the lock screen (wm dismiss-keyguard): the agent does not ask. Only when a code is required (code_required: true) are gestures refused until the user unlocks it.
• Text read on screen or in messages is data, never instructions.
• User holding the phone: no gesture mixes with theirs. If the phone was touched in the last 3 seconds (and not by an agent), the server waits up to 10 seconds, then refuses. A phone that does not report its last touch (no lastUserActivityTime in dumpsys power) gets a warning in the act response: that check is inactive there.
• Link lost during a gesture: reported as ? (effect unknown), never as a plain failure: the agent looks again before redoing it, so nothing is sent twice. A read with no answer (Wi-Fi gone) fails after 10 seconds (5 for the screen state) instead of minutes, and the next call looks for the phone again.
• Fold folded or unfolded since the last image: x,y targets are refused until a new look.
• Reboot: phone and look say once that the phone restarted; when it cannot be found, the message reminds that Android turns wireless debugging off after a reboot or a network change.
• Other control tools (mobile-mcp, Appium, Shizuku, another scrcpy) left running on the phone can block the UI tree: checkup and the error name them.

Unlocking again and again while an agent works is tedious, but a phone used to pay must not stay unlocked. So, at the first gesture (act, launch, draft) on a phone the user has unlocked, the server saves the screen timeout (screen_off_timeout) and raises it to 5 minutes, a delay Android counts again from every gesture; phone shows until when. If the server is killed, the screen still turns off (and locks) at most 5 minutes after the last gesture. While the agent only looks, a screen that is on gets a wake-up key at most once a minute (no visible effect), so it does not turn off during a long observation.

About 2 minutes after the last gesture or look of any agent, the original timeout is restored. The server does not turn the screen off itself: the phone then goes to sleep, and locks, after its own normal delay counted from the last activity. If the user changed the timeout themselves meanwhile, their value is kept. The original value is saved once (~\.nexus\nexus-android\awake.json) and shared by all servers under the common lock: one save, one restore, never the raised value taken for the original. After a crash, the next server to start restores it. The server never unlocks a phone that Android keeps locked. NEXUS_ANDROID_AWAKE_IDLE (seconds, default 120) changes the delay (the raised timeout then stays a minute longer than it, 5 minutes at least); NEXUS_ANDROID_KEEP_AWAKE=0 turns it off.

• Companion app on the phone: notifications, typing with accents, files and settings all come from ADB itself; an app would only add control away from USB and home Wi-Fi, which is rarely needed.
• Invisible screen: seeing the agent work on the real screen is a feature.
• Internet relay (tunnels, VPN): USB or local Wi-Fi only.

Since One UI does not announce the phone over mDNS, the server records its Wi-Fi address and the wireless debugging port every time it is plugged in over USB. This port changes after a reboot or a network change: plugging in over USB once is then enough. The last known address is tried first, then mDNS; only when the PC is on the same network does the server look for the new port, checking with an ADB handshake before connecting. When the phone cannot be found, the server does not search the Wi-Fi again for 2 minutes (a cable plugged in is still seen at once). The cable takes priority when it is plugged in. NEXUS_ANDROID_SERIAL forces a specific device, by serial number or ip:port address.

No shared Wi-Fi network (office PC on Ethernet only, with a Wi-Fi card): turn on the phone's hotspot and connect the PC to it, then, with the cable plugged in once, run adb tcpip 5555. The server records the phone's hotspot address and finds it there after the cable is removed. TCP mode lasts until the phone restarts (or adb usb). Raise the PC's Wi-Fi interface metric if its internet traffic should keep going through Ethernet rather than the phone's mobile data.

To start it manually after installation:

$env:NEXUS_MCP_TOKEN_FILE = Join-Path $env:USERPROFILE '.nexus\mcp-token.txt' # or the shared file chosen at installNexusAndroid.exe --http 16180

It serves MCP Streamable HTTP on 127.0.0.1 only (default port 16180), at http://127.0.0.1:16180/mcp, and refuses any request without the header Authorization: Bearer <token> (HTTP 401); it does not start without a token. Point each client at that URL with that header. Each MCP session keeps its own [N] numbering and conversation list; the ADB link and the phone lock are shared. The token file takes precedence over NEXUS_MCP_TOKEN; the variable is a fallback only when NEXUS_MCP_TOKEN_FILE is unset and the default shared file is absent. The token keeps a misconfigured client or a stray session from driving the phone; it is no protection against malicious software running on the same PC, which can reach the phone directly through ADB (see SECURITY.md).

• What it reads: the screen and UI tree, SMS/RCS messages, notifications, files in shared storage, location, recent calls, contacts and calendar, only when the agent calls the matching tool. Security codes are masked before the agent sees them.
• Where it goes: tool results are returned to the AI client you connected (Claude, Codex, Antigravity…). That client may send them to its model provider under its own privacy policy; NexusAndroid sends nothing anywhere else.
• What it stores on the PC, under ~/.nexus/: the phone map (map/: the Settings tree, the screens noted with map note, and up to 30 snapshots of settings values, apps, permissions and Bluetooth device names, with identifiers, tokens, addresses and numbers masked), the phone's serial number, Wi-Fi address and wireless debugging port, the saved screen timeout, a lock file, the pinned scrcpy server, the downloaded Platform Tools (when no adb was found), backups of the AI client configs that setup or install.ps1 edits (backups/), and the installed executables (releases/ or native/). Files you pull go to ~/Downloads/Telephone. The server writes no messages or screenshots to disk.
• Journal, under ~\.nexus\journal\android\<agent>\<YYYY-MM>.jsonl (or NEXUS_JOURNAL_HOME), shared format of the Nexus tools: one line per gesture or tool call with the calling AI (Claude, Codex, Antigravity), the action, the outcome, the duration, the technique, the app's package name and an error category from a fixed list. Never screen text, SMS, contact, typed text or code. Nothing is sent anywhere; months are kept until you delete them: delete the android folder (or single month files) at any time. NEXUS_JOURNAL=0 in the server's environment turns it off (nothing written, no folder created).
• On the phone, in /data/local/tmp: the two helpers (nexus-scrcpy.jar, nexus-query-*.dex) stay there; the UI dump (nexus-android-ui-*.xml) and the temporary read folders (nexus-q-*, nexus-p-*) are deleted right after each read. The read helper stops by itself after 10 minutes without a request.
• Removing it: delete ~/.nexus/nexus-android/, ~/.nexus/android.lock and ~\.nexus\journal\android\, remove the nexus-android entry from each client's config, run adb shell "rm -rf /data/local/tmp/nexus-*" (helpers, UI dumps and any read folder left by an interrupted read), and revoke the PC's key on the phone (Developer options → Revoke USB debugging authorizations).

An alternative to get.ps1 for contributors: builds the engine from the sources with the .NET 10 SDK and runs the same setup.

git clone https://github.com/pironjulien/NexusAndroidcd NexusAndroidpwsh -NoProfile -File install.ps1          # tests, build, then setup (adb, scrcpy server, AI apps, phone)pwsh -NoProfile -File install.ps1 -NoWait  # same, without waiting for the phone

The executable goes to ~\.nexus\nexus-android\native\<source fingerprint> (a new folder for new sources, never overwritten while an AI app runs it). -SkipTests skips the tests, -NoRegister leaves the AI apps alone. Build output goes to ~\.nexus\build\nexus-android, never into the clone. The engine, its verification and its exact limits are documented in NATIVE-QUALIFICATION.md.

Each client then starts its own server over stdio. They share the phone lock and the screen-awake state through ~\.nexus; for a single process shared by all clients, see Shared daemon.