android-agent-bridge 0.1.2 → 0.1.4

package/README.md

@@ -16,7 +16,13 @@ One `npx` command on the computer, one QR scan on the phone.
 [![MCP](https://img.shields.io/badge/MCP-27%20tools%20%C2%B7%206%20prompts-3ddc97)](#for-agents)
 [![License: MIT](https://img.shields.io/badge/license-MIT-3ddc97)](LICENSE)
 
-[**Website**](https://rudrasamadhiya.github.io/android-agent-bridge/) · [**Get started**](https://rudrasamadhiya.github.io/android-agent-bridge/start/) · [**Docs**](https://rudrasamadhiya.github.io/android-agent-bridge/docs/) · [**Download the app**](https://github.com/Rudrasamadhiya/android-agent-bridge/releases/latest/download/agent-bridge.apk)
+[**Website**](https://rudrasamadhiya.github.io/android-agent-bridge/) · [**Get started**](https://rudrasamadhiya.github.io/android-agent-bridge/start/) · [**Docs**](https://rudrasamadhiya.github.io/android-agent-bridge/docs/) · [**Install the app**](https://rudrasamadhiya.github.io/android-agent-bridge/download/#install)
+
+<br/>
+
+<a href="https://rudrasamadhiya.github.io/android-agent-bridge/video/"><img src="https://raw.githubusercontent.com/Rudrasamadhiya/android-agent-bridge/main/docs/video/preview.gif" width="720" alt="Agent Bridge in 6 seconds: an agent taps, types and scrolls a real phone. Click to watch the full film." /></a>
+
+**[▶ Watch the film (1:30)](https://rudrasamadhiya.github.io/android-agent-bridge/video/)**
 
 <br/>
 
@@ -45,7 +51,9 @@ One `npx` command on the computer, one QR scan on the phone.
 npx android-agent-bridge usb
 ```
 
-It installs the app, switches on its accessibility service, pairs and starts the bridge.
+It installs the app, switches on its accessibility service, pairs and starts the bridge. If you don't have Android's adb tool, it downloads it from Google the first time.
+
+> **No cable?** On Android 11+, turn on *Wireless debugging* in Developer options and run `npx android-agent-bridge wifi`, then scan the QR code from *Pair device with QR code*.
 
 **2. Connect your agent.** For Claude Code:
 
@@ -72,7 +80,7 @@ npx android-agent-bridge start
 
 In the app: **Scan QR code** → point it at the code in your terminal (or the bigger one at `localhost:8350/pair`) → turn on the **accessibility service**. Phone and computer must be on the same Wi-Fi.
 
-If Play Protect says *"App blocked to protect your device"*, install over USB with `usb` instead. Installs over USB aren't blocked.
+If Play Protect says *"App blocked to protect your device"*, install from your computer instead with `usb` or `wifi`. Play Protect blocks sideloaded accessibility apps opened from a browser or chat app; installs through adb aren't affected.
 
 </details>
 
@@ -206,7 +214,7 @@ Apps that block screen capture (banking, streaming) show up black in screenshots
 
 <br/>
 
-- **"App blocked to protect your device":** install over USB with `npx android-agent-bridge usb`.
+- **"App blocked to protect your device":** install from your computer with `npx android-agent-bridge usb`, or `npx android-agent-bridge wifi` (Android 11+, no cable).
 - **No phone connected:** is `start` running? Same Wi-Fi? On Windows, allow Node.js through the firewall. Over USB, run `usb` again.
 - **Accessibility switch greyed out** (Android 13+): App info → ⋮ → Allow restricted settings.
 - **A tap opened nothing right after Home:** Android holds app starts for about 5 seconds after Home; run it again.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "android-agent-bridge",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Give AI agents (Claude Code, Cursor, Antigravity) your whole Android phone: screenshots with numbered elements and a tap grid, tap, type, scroll, open apps. Pair once by QR over Wi-Fi or plug in USB. Android 5.0+.",
   "keywords": [
     "android",

package/server/adb.mjs

@@ -2,9 +2,13 @@
 // fallback for what the app cannot do on old Android (taps by coordinate
 // before Android 7, Enter key before Android 11, screenshots without capture).
 import { execFile } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
+// Where platform-tools is downloaded when the computer has no Android SDK.
+const OWN_TOOLS = path.join(os.homedir(), '.android-agent-bridge', 'platform-tools');
+
 export const KEYCODES = {
   back: 4, home: 3, recents: 187, enter: 66, tab: 61, delete: 67, escape: 111,
   volume_up: 24, volume_down: 25, mute: 164, power: 26, menu: 82, search: 84,
@@ -18,13 +22,42 @@ export function adbPath() {
     process.env.HOME && path.join(process.env.HOME, 'Android', 'Sdk')]) {
     if (root && existsSync(path.join(root, 'platform-tools', exe))) return path.join(root, 'platform-tools', exe);
   }
+  if (existsSync(path.join(OWN_TOOLS, exe))) return path.join(OWN_TOOLS, exe);
   return 'adb';
 }
 
+/**
+ * Makes sure adb exists. Without an Android SDK or adb on PATH, downloads Google's
+ * platform-tools (about 7 MB) into ~/.android-agent-bridge once.
+ */
+export async function ensureAdb(log = console.log) {
+  try { await adb(['version'], { serial: null }); return; } catch (e) { if (!/adb not found/.test(e.message)) return; }
+  const plat = process.platform === 'win32' ? 'windows' : process.platform === 'darwin' ? 'darwin' : 'linux';
+  const url = `https://dl.google.com/android/repository/platform-tools-latest-${plat}.zip`;
+  log('adb (Android platform-tools) not found; downloading it from Google, one time only…');
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Couldn't download platform-tools (${res.status}). Install it yourself: https://developer.android.com/tools/releases/platform-tools`);
+  const base = path.dirname(OWN_TOOLS);
+  mkdirSync(base, { recursive: true });
+  const zip = path.join(base, 'platform-tools.zip');
+  writeFileSync(zip, Buffer.from(await res.arrayBuffer()));
+  rmSync(OWN_TOOLS, { recursive: true, force: true });
+  await new Promise((resolve, reject) => {
+    const [bin, args] = process.platform === 'win32'
+      ? ['powershell', ['-NoProfile', '-Command', `Expand-Archive -LiteralPath '${zip}' -DestinationPath '${base}' -Force`]]
+      : ['unzip', ['-q', '-o', zip, '-d', base]];
+    execFile(bin, args, { windowsHide: true, timeout: 120000 }, (err) => (err ? reject(new Error('Couldn\'t unpack platform-tools: ' + err.message)) : resolve()));
+  });
+  rmSync(zip, { force: true });
+  if (process.platform !== 'win32') chmodSync(path.join(OWN_TOOLS, 'adb'), 0o755);
+  log('✔ adb ready');
+}
+
 export function adb(args, { timeout = 15000, binary = false, serial = process.env.ANDROID_SERIAL } = {}) {
   const full = serial ? ['-s', serial, ...args] : args;
   return new Promise((resolve, reject) => {
-    execFile(adbPath(), full, { timeout, windowsHide: true, encoding: binary ? 'buffer' : 'utf8', maxBuffer: 64 * 1024 * 1024 }, (err, stdout, stderr) => {
+    // ADB_MDNS_OPENSCREEN lets adb find phones over Wi-Fi (wireless debugging) on every platform
+    execFile(adbPath(), full, { timeout, windowsHide: true, encoding: binary ? 'buffer' : 'utf8', maxBuffer: 64 * 1024 * 1024, env: { ...process.env, ADB_MDNS_OPENSCREEN: '1' } }, (err, stdout, stderr) => {
       if (err) {
         reject(new Error(err.code === 'ENOENT'
           ? 'adb not found. Install Android platform-tools (https://developer.android.com/tools/releases/platform-tools) or set ANDROID_HOME.'

package/server/cli.mjs

@@ -3,6 +3,7 @@
 //   (no command)      MCP server, launched by AI agents
 //   start             run the bridge and show the pairing QR code
 //   usb               set up a USB-connected phone (install, permissions, pair)
+//   wifi              same, without a cable (Android 11+ wireless debugging)
 //   init              add the MCP server + agent guide to the current project
 //   status | screen | elements | tap | type | scroll | swipe | key | open | apps | wait
 import fs from 'node:fs';
@@ -11,7 +12,8 @@ import { fileURLToPath } from 'node:url';
 import { Bridge } from './bridge.mjs';
 import { loadConfig, resetToken, APP_ID } from './config.mjs';
 import { lanAddresses, pairLink, qrTerminal } from './hub.mjs';
-import { adb, devices, pickSerial } from './adb.mjs';
+import { adb, devices, ensureAdb, pickSerial } from './adb.mjs';
+import readline from 'node:readline/promises';
 import { fmtSize } from './files.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -37,6 +39,7 @@ const HELP = `android-agent-bridge — let AI agents use your Android phone
 Setup
   start                      run the bridge and show the QR code to pair over Wi-Fi
   usb                        set up a phone plugged in over USB (install app, permissions, pair)
+  wifi [--code]              same without a cable: Android 11+ wireless debugging, pair by QR (--code: pairing code)
   init                       add the MCP server and agent guide to this project
   pair [--reset]             show the QR code again (--reset: new secret, phones must re-scan)
   (no command)               MCP server (what Claude Code / Cursor / Antigravity launch)
@@ -256,12 +259,92 @@ function findApk() {
 }
 
 async function usb() {
-  const { flags } = parseArgs(rest);
-  const list = await devices().catch((e) => die(e.message));
+  await ensureAdb().catch((e) => die(e.message));
+  // a freshly started adb takes a moment to see a phone, so look a few times before giving up
+  let list = [];
+  for (let i = 0; i < 8 && !list.length; i++) {
+    list = await devices().catch((e) => die(e.message));
+    if (list.length) break;
+    const raw = await adb(['devices'], { serial: null }).catch(() => '');
+    if (/\tunauthorized/.test(raw)) {
+      if (i === 0) console.log('Phone found. On the phone, tap "Allow" on the "Allow USB debugging?" prompt (tick "Always allow").');
+    } else if (i >= 3) break;
+    await wait(1500);
+  }
   if (!list.length) {
-    die('No phone found over USB.\n1. Settings → About phone → tap "Build number" 7 times (developer mode).\n2. Settings → Developer options → turn on USB debugging.\n3. Plug the phone in and accept the "Allow USB debugging?" prompt.');
+    die('No phone found over USB.\n1. Settings → About phone → tap "Build number" 7 times (developer mode).\n2. Settings → Developer options → turn on USB debugging.\n3. Plug the phone in and accept the "Allow USB debugging?" prompt.\n\nNo cable? Android 11+ can do this over Wi-Fi: npx android-agent-bridge wifi');
   }
-  const serial = await pickSerial();
+  await setUp(await pickSerial());
+}
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Wireless-debugging services the phone announces on the network: [{ name, type, addr }]. */
+async function mdnsServices() {
+  const out = await adb(['mdns', 'services'], { serial: null }).catch(() => '');
+  return out.split('\n').map((l) => l.trim().split(/\s+/)).filter((p) => p.length >= 3 && p[1].startsWith('_adb-tls'))
+    .map(([name, type, addr]) => ({ name, type, addr }));
+}
+
+/**
+ * Same as `usb`, but without a cable: Android 11+ "Wireless debugging". The phone scans a QR code
+ * from this terminal (or types a pairing code), then adb installs and sets up the app over Wi-Fi.
+ * Installs through adb are not blocked by Play Protect.
+ */
+async function wifi() {
+  const { flags } = parseArgs(rest);
+  await ensureAdb().catch((e) => die(e.message));
+  console.log('\nInstall Agent Bridge over Wi-Fi (Android 11 or newer, phone on the same Wi-Fi as this computer)\n');
+  console.log('On the phone:');
+  console.log('  1. Settings → About phone → tap "Build number" 7 times (once, turns on developer options)');
+  console.log('  2. Settings → Developer options → Wireless debugging → turn it on');
+
+  let paired = false;
+  if (!flags.code) {
+    const name = 'agentbridge-' + Math.random().toString(36).slice(2, 7);
+    const pass = String(Math.floor(100000 + Math.random() * 900000));
+    console.log('  3. Tap "Pair device with QR code" and scan this:\n');
+    console.log(await qrTerminal(`WIFI:T:ADB;S:${name};P:${pass};;`));
+    console.log('Waiting for the phone… (no QR option? Ctrl+C and run: npx android-agent-bridge wifi --code)');
+    for (let i = 0; i < 180 && !paired; i++) {
+      const svc = (await mdnsServices()).find((s) => s.name === name && s.type.startsWith('_adb-tls-pairing'));
+      if (svc) {
+        const out = await adb(['pair', svc.addr, pass], { serial: null, timeout: 30000 }).catch((e) => e.message);
+        if (!/Successfully paired/i.test(out)) die('Pairing failed: ' + out);
+        paired = true;
+      } else await wait(1000);
+    }
+    if (!paired) die('The phone did not show up. Check both are on the same Wi-Fi, or try: npx android-agent-bridge wifi --code');
+  } else {
+    console.log('  3. Tap "Pair device with pairing code"\n');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const addr = (await rl.question('IP address & port shown in that dialog (e.g. 192.168.1.5:37000): ')).trim();
+    const code = (await rl.question('Wi-Fi pairing code: ')).trim();
+    rl.close();
+    const out = await adb(['pair', addr, code], { serial: null, timeout: 30000 }).catch((e) => e.message);
+    if (!/Successfully paired/i.test(out)) die('Pairing failed: ' + out);
+  }
+  console.log('✔ Paired with the phone for wireless debugging');
+
+  // after pairing the phone announces a connect service; adb usually connects to it by itself
+  let serial = null;
+  for (let i = 0; i < 30 && !serial; i++) {
+    const list = await devices().catch(() => []);
+    const wireless = list.find((d) => d.serial.includes('_adb-tls-connect') || /:\d+$/.test(d.serial));
+    if (wireless) { serial = wireless.serial; break; }
+    for (const s of (await mdnsServices()).filter((x) => x.type.startsWith('_adb-tls-connect'))) {
+      await adb(['connect', s.addr], { serial: null }).catch(() => {});
+    }
+    await wait(1000);
+  }
+  if (!serial) die('Paired, but could not connect. On the phone, check Wireless debugging is still on and run this again.');
+  console.log('✔ Connected over Wi-Fi');
+  await setUp(serial);
+}
+
+/** Installs the app if needed, switches on its accessibility service, pairs it and runs the bridge. */
+async function setUp(serial) {
+  const { flags } = parseArgs(rest);
   const sh = (...c) => adb(['shell', ...c], { serial });
   const cfg = loadConfig();
   const sdk = Number(await sh('getprop', 'ro.build.version.sdk'));
@@ -348,6 +431,7 @@ try {
   } else if (cmd === 'help' || cmd === '--help' || cmd === '-h') console.log(HELP);
   else if (cmd === 'start') await start();
   else if (cmd === 'usb') await usb();
+  else if (cmd === 'wifi') await wifi();
   else if (cmd === 'init') init();
   else if (cmd === 'pair') {
     const cfg = parseArgs(rest).flags.reset ? resetToken() : loadConfig();