AI Termux WADB Toolkit: Give a Compatible AI Assistant a Working Android Environment

Most phone-based AI workflows still involve a lot of manual shuffling: locate a file, upload it to a chat, copy a suggested command into a terminal, paste the output back, and repeat.

Just send this tool kit to ai like chat gpt,Claude or grock and ask how to setup the tool kit and tell ai to do the setup,Ai should give u instruction to setup initial desktop commander plugin or MCP and after the desktop commander is set the ai can install the tool kit by it self I'm termux or u can tell it to do so and then u only need to to initial wireless adb and bootstrap set which is automatically done by tool u just need to provide the pairing code to ai when it ask u to.If you face any problem ask ai to check the instructions and reference md or text files or u can ask here feel free.

AI Termux WADB Toolkit is designed to let a compatible AI assistant work directly with an authorised Termux environment on an Android phone. After the owner completes the initial connection and permission setup, the assistant can run available Termux commands, work with files Termux can access, use the Toolkit's Android-control routes, and save results on the phone.

It is not a magic remote-control app, and it does not bypass Android permissions. It connects existing Android and command-line components into one workflow.

This article describes AI Termux WADB Toolkit v1.0.1.

You describe a task in an AI app | v AI client with a compatible MCP connection | v Remote Desktop Commander (running from Termux) | v Termux shell + AI Termux WADB Toolkit + installed packages | +-----+-------------------+ | | v v Wireless ADB Secure Local Shell | | +------------+------------+ | v Android shell WADB Bridge is the Android companion used for supported Wireless Debugging controls and Android-side recovery. Enter fullscreen mode Exit fullscreen mode These are separate layers:

Termux is the Android terminal application. It provides a shell, its own package manager (pkg), a home directory, and the programs installed by the owner.

The Toolkit is installed inside Termux, not as a normal Android app with a launcher screen.

/data/data/com.termux/files/usr/bin/ Toolkit commands such as ai-info, wireless-debug-on, wadb-local-on and wadb-mcp-start /data/data/com.termux/files/usr/libexec/ai-wadb/ Shared shell helpers, the native local bridge and verifier /data/data/com.termux/files/home/AI_WADB_DOCS/ Installed User Guide, AI Guide, Command Reference, Technical Reference and toolkit manifest /data/data/com.termux/files/home/AI_ENVIRONMENT.md Installed environment and AI workflow reference /data/data/com.termux/files/home/.ai-wadb/ Toolkit state, local-shell token, cached WADB Bridge APK, recovery configuration and private runtime files Enter fullscreen mode Exit fullscreen mode The installer checks for tools such as Python, Android platform-tools (adb), core utilities, flock, curl and Git. Node.js/npm are needed for Desktop Commander. Optional features may need additional packages.

Desktop Commander is a separate project and dependency. The Toolkit does not bundle an AI model or Desktop Commander itself.

The phone-side service is started from Termux with:

npx @wonderwhy-er/desktop-commander@0.3.1 remote Enter fullscreen mode Exit fullscreen mode The owner completes the normal browser/device verification and connects an AI client that supports the relevant Remote MCP integration. Desktop Commander exposes authorised terminal, file, directory and process tools to that client.

The Toolkit then gives the assistant clear commands and instructions for managing Android connectivity and the phone-side service.

The Toolkit itself is a collection of Bash scripts, a small native C helper, Android companion source, install/uninstall logic, diagnostics, recovery code and documentation.

Its main entry point is ai-info. It gives a human-readable dashboard and interactive Control Center. The machine-readable interface is ai-info --json, which lets an AI inspect actual state instead of guessing from a terminal screen.

WADB Bridge is the small Android package com.jaskran.wadbbridge, included in the release and installed as a separate Android component during authorised setup.

It provides the protected receiver used by the Toolkit to read and change Android's Wireless Debugging setting, plus a Termux recovery hand-off and its own recovery notification channel. It has no normal app-drawer launcher screen; it works as a companion component.

During first authorised setup, ADB grants the required WRITE_SECURE_SETTINGS permission to Termux and WADB Bridge. The Bridge receiver is protected by that permission. The Toolkit verifies that the grants and the Bridge's read/write path really work.

There are two separate Termux:API pieces:

Installing one does not install the other. They are optional. They add capabilities such as Wi-Fi connection information and Termux-side Android notifications. Core command execution and the main Toolkit workflow do not depend on notifications.

The Toolkit uses Android's ADB and mDNS discovery mechanisms, Android package and settings services, shell utilities, Python, Node.js, Git, and a native C loopback helper. Desktop Commander is the MCP transport; the Toolkit's Bash scripts are the control interface; the Java Android Bridge is the privileged settings/recovery companion.

Optional GitHub recovery uses the GitHub CLI (gh), a restricted local read token, or anonymous Git reads depending on the mode selected. The GitHub CLI is not required for normal use.

The repository contains the actual implementation, not just setup notes. These are the main entry points and what they do:

For Wireless Debugging toggles, the key Android API is Settings.Global with the adb_wifi_enabled key. Initial authenticated ADB setup grants WRITE_SECURE_SETTINGS to Termux and WADB Bridge. After those grants are verified, the two wireless-debug scripts use the Bridge receiver directly, so each later ON/OFF request does not need an already-connected ADB transport. ADB pairing and reconnection remain separate operations.

The local C helper is not an ADB server. It listens only on the phone's loopback interface, authenticates requests with a random token and runs as Android uid=2000(shell). The Bridge recovery receiver invokes only the fixed Toolkit recovery job; it is not a general-purpose remote shell.

The Wireless Debugging toggle is not an ADB command pretending to be a setting switch. The Toolkit uses a small Android component and Android's protected settings API:

The Termux helpers wireless-debug-status, wireless-debug-on and wireless-debug-off call that receiver through Android's /system/bin/am broadcast command. For example, the ON request is sent to the explicit component com.jaskran.wadbbridge/.WirelessDebugReceiver with the SET_WIRELESS_DEBUG action and enabled=true; OFF sends the same action with enabled=false. The scripts verify the broadcast result and read the setting back instead of treating a successful command exit as proof.

During the one-time authorised bootstrap, wadb-bootstrap uses the authenticated ADB shell to install/update WADB Bridge and grant/verify WRITE_SECURE_SETTINGS for both the Bridge and Termux. Termux needs the grant to call the receiver protected by that permission; the Bridge needs it to use Settings.Global. Once those grants are present, each later ON/OFF toggle is a local Termux-to-Bridge broadcast and does not need an active ADB transport. Removing either grant or uninstalling the Bridge breaks this route until setup is repaired.

Enabling the setting is not the same as pairing or connecting ADB. The Python helper scripts/adb-mdns-discover queries Android DNS-SD/mDNS service types _adb-tls-pairing._tcp.local and _adb-tls-connect._tcp.local on multicast DNS. It identifies pairing and normal connection endpoints separately. wireless-adb-connect then uses the ADB client and the saved trusted key; a fresh adb pair flow is needed only when Android says pairing is required. The connection/port details are rediscovered because they can change.

The Secure Local Shell uses a different mechanism again. native/wadb-local-bridge.c creates a TCP socket bound to INADDR_LOOPBACK (127.0.0.1), listens on port 47173 by default, checks a 64-character random token, and executes accepted commands through /system/bin/sh -c as Android uid=2000(shell). The token is kept in Termux under ~/.ai-wadb/ with restrictive file permissions. This helper is not an ADB server and is not exposed on the phone's Wi-Fi interface. In the steady state, classic adbd TCP exposure is disabled ( service.adb.tcp.port=0 ); the ADB daemon can remain enabled for the supported local shell arrangement. The first deployment or repair of this helper may still need authenticated Wireless ADB.

The Android recovery hand-off also uses a named platform interface. McpRecoveryReceiver handles android.intent.action.BOOT_COMPLETED and android.intent.action.MY_PACKAGE_REPLACED, schedules a slower fallback with AlarmManager.setInexactRepeating() at a fifteen-minute interval, and asks Termux to run the fixed wadb-mcp-job script through com.termux.app.RunCommandService using the com.termux.RUN_COMMAND action. The related Android permission is com.termux.permission.RUN_COMMAND; PermissionActivity requests it when it is not already granted. The receiver does not accept an arbitrary shell command from an external caller.

The faster Termux watchdog is separate from that Android alarm. Its recovery scripts manage the Desktop Commander desired/actual state and normally check at about fifteen-second intervals. Optional GitHub recovery reads a narrowly scoped control file and accepts only the documented actions START_MCP, STOP_MCP, RESTART_MCP and STATUS.

Termux:API is optional. The current scripts use commands such as termux-wifi-connectioninfo for Wi-Fi information and termux-notification for local state-change notifications. The command package and compatible Android companion app are separate installs; missing notifications do not disable the core Toolkit workflow.

For the AI connection, Desktop Commander is the external Remote MCP service started with npx @wonderwhy-er/desktop-commander@0.3.1 remote. Its connected tools include terminal/process operations such as start_process, read_process_output and interact_with_process, plus filesystem/directory operations such as read_file, write_file, read_multiple_files and list_directory. The Toolkit does not implement those general-purpose tools itself; it provides the Android-specific command suite and instructions that the AI uses through Desktop Commander.

Initial setup means establishing the trust and permissions that Android and the AI connection require once. It is not something that should be repeated for every command.

Install Termux from a compatible source. Open it and run:

pkg update pkg install nodejs npm termux-setup-storage Enter fullscreen mode Exit fullscreen mode Approve Android's storage prompt if you want the AI to work with shared files such as Downloads. The Toolkit installer checks and installs its required Termux packages. Do not assume Termux can see another app's private data: Android sandboxing still applies.

Extract the official Toolkit release ZIP into a Termux-accessible folder, open that extracted directory in Termux, and follow the release verification and installation steps in its README/User Guide.

Run the installer from the extracted project directory:

bash install.sh Enter fullscreen mode Exit fullscreen mode The installer performs release verification and an install-path preflight before changing Toolkit files. It then installs the commands, shared helpers, documentation and WADB Bridge APK cache, and runs post-install checks. The release's independent trust values are part of the installation security process; use the values published with the official release, not values guessed from the archive being checked.

In Termux, start the phone-side service:

npx @wonderwhy-er/desktop-commander@0.3.1 remote Enter fullscreen mode Exit fullscreen mode Complete the browser/device verification when prompted. Then connect a compatible AI client through its available Desktop Commander/Remote MCP integration and approve the connection.

Uploading the ZIP or AI guide to a chat does not establish this connection. The real MCP connection must be authorised.

ai-info ai-info --connect Enter fullscreen mode Exit fullscreen mode On a fresh phone, Android may require the owner to enable Developer options → Wireless debugging and open Pair device with pairing code. When the Toolkit reports RESULT=PAIRING_REQUIRED, keep that Android popup open and provide the current six-digit code:

ai-info --pair 123456 Enter fullscreen mode Exit fullscreen mode Only use the code from the current popup. Do not run ai-info --connect again while the Toolkit says a pairing code is pending; use ai-info --pair CODE.

On OPPO/ColorOS, OnePlus and realme builds where the OEM restriction applies, Disable permission monitoring in Developer options may also need to be switched ON (blue) before the ADB permission-grant step. The Toolkit reports the relevant state when it can read it.

Once authenticated ADB is available, the Toolkit installs or updates WADB Bridge and uses the ADB shell to grant and verify the required secure-settings permissions. Setup is complete only when the command reports:

RESULT=CONNECTED_AND_READY bridge_write=ready Enter fullscreen mode Exit fullscreen mode The owner may need to approve Android permission dialogs or complete browser login. Android controls those approvals.

After this one-time setup, saved ADB trust and Bridge permissions can normally be reused. Pairing is not required for every reconnect unless Android's trust state is revoked or the phone requires a new pairing session.

This is one of the important distinctions in the Toolkit.

Before setup, the owner needs to enable Wireless Debugging manually at least once so the phone can be paired and the required permission grants can be made.

After setup, the Toolkit can use WADB Bridge to read and change the Wireless Debugging setting. It does not need an already-connected Wireless ADB transport just to send the later ON/OFF request. The Bridge's Android receiver performs the setting operation, and the scripts read the result back to verify it.

wireless-debug-status wireless-debug-on wireless-debug-off Enter fullscreen mode Exit fullscreen mode Or use the interactive Control Center with ai-info. Its Wireless ADB disconnect option offers two different actions:

ai-info --disconnect-transport --confirm ai-info --wireless-off --confirm Enter fullscreen mode Exit fullscreen mode The important separation:

Turning Wireless Debugging ON is not the same as connecting ADB. ADB still needs a trusted key and, when required, a valid pairing. The Toolkit handles discovery and reconnect separately.

The Toolkit includes a second Android shell route called Secure Local Shell.

It is prepared through an already-authorised Android shell connection. The Toolkit stages its native C helper on the phone, starts it as Android's uid=2000(shell) user, and authenticates the local connection with a random token stored privately in Termux.

The helper listens only on 127.0.0.1:47173. It is loopback-only, not an ADB TCP listener exposed to the Wi-Fi network. The Toolkit verifies that classic adbd TCP exposure is absent in the secure steady state.

wadb-local-on wadb-local-status wadb-local-shell -c 'id' Enter fullscreen mode Exit fullscreen mode Stop it with:

wadb-local-off --confirm Enter fullscreen mode Exit fullscreen mode Once initialised, this route can be used for supported Android shell tasks when Wireless Debugging is OFF. It does not silently become root.

There is an important bootstrap detail: if the local helper is missing and has to be staged again, wadb-local-on may temporarily use Wi-Fi and authenticated Wireless ADB to install/start it. After successful setup it turns Wireless Debugging off and restores Wi-Fi to its previous OFF state when possible. In other words, the steady-state local shell is Wi-Fi-independent; recovery/bootstrap can temporarily need Wi-Fi and Wireless ADB.

A reboot, adbd restart, force-stop or manufacturer background restriction can stop the helper. Rerun wadb-local-on when required. Persistence across every reboot is not promised.

The Toolkit manages the phone-side Desktop Commander process without confusing a stop with a logout.

wadb-mcp-status wadb-mcp-start wadb-mcp-stop wadb-mcp-restart wadb-mcp-log --follow Enter fullscreen mode Exit fullscreen mode start brings the managed service online while preserving saved authorisation. stop records desired state as offline and stops the process. restart stops and starts it again without deliberately clearing the saved login. status reports actual and desired state, process count, watchdog and recovery information. log --follow follows the existing log; Ctrl+C stops only the viewer. wadb-mcp-logout --confirm is intentionally different: it removes saved authorisation. It is not a normal restart or recovery command.

After the first successful Desktop Commander login:

wadb-mcp-recovery-setup ai-info --recovery Enter fullscreen mode Exit fullscreen mode The local watchdog can restore Desktop Commander when recovery is enabled, desired state is online and the process is missing. It respects an intentional offline state. wadb-mcp-recovery-disable is the separate master switch for disabling the recovery watchdog.

WADB Bridge also has an Android-side recovery receiver for supported events such as boot and package replacement. It requests the fixed Termux recovery job; it does not provide a general-purpose remote command service.

GitHub recovery is an independent fallback path for cases where MCP is offline but the AI can still access GitHub.

The AI-side GitHub connector writes a small, validated control file. The phone-side reader fetches it and can process supported START_MCP, STOP_MCP, RESTART_MCP and STATUS actions. The phone can read using:

The AI writer and phone reader do not need to use the same GitHub account. The first sync of a new control identity establishes a baseline and does not execute an old action already present in the file. GitHub recovery is optional; it is not needed for ordinary WADB use.

ai-info is the main control centre for the owner and the preferred status interface for the AI.

ai-info # human dashboard and interactive menu ai-info --json # structured status for an AI ai-info --doctor # read-only diagnostics ai-info --connect # Wireless ADB connect/setup ai-info --local # Secure Local Shell status ai-info --local-on # enable/repair Secure Local Shell ai-info --local-off --confirm ai-info --recovery # recovery state ai-info --disconnect # transport-only or Wireless Debugging OFF menu ai-info --commands # complete command catalogue Enter fullscreen mode Exit fullscreen mode Additional command families:

Use ai-info --commands or the included Command Reference for exact syntax, side effects, requirements and confirmation rules of every command.

Once the MCP connection is authorised, the assistant can use the normal Termux environment, not just the Toolkit's own commands. Available work depends on installed packages, filesystem permissions granted to Termux, the connected AI client's tools and Android's privilege boundaries.

“Inspect the project in Downloads, identify the build error, fix it in a separate copy, run the available tests and save the corrected project.”

“Check the MCP, Wireless ADB, Bridge and local-shell states. Tell me what is available before making any changes.”

“Turn Wireless Debugging off, but keep the Desktop Commander session and Secure Local Shell running. Verify each state afterwards.”

The assistant should inspect state before acting and verify afterwards. The Toolkit instructions ask compatible AI clients to use the documented helper for managed operations rather than guessing lower-level commands.

On a rooted device, an owner-approved su route may allow additional tasks. On a non-rooted device, work is limited to Termux's permissions and the Android shell capabilities available through the authorised route. Wireless ADB and Secure Local Shell run as Android's shell user, not root.

The Toolkit's own source is licensed under Apache-2.0. Desktop Commander, Termux, Android and other third-party components remain their respective projects and retain their own licences. The Toolkit is independent; it is not an official Termux, Android or Desktop Commander product.

Project repository: https://github.com/jaskran0417/ai-termux-wadb-toolkit

I want to hear how this works on actual devices, not just in my development environment.

Please share your Android model and Android version, whether initial pairing and Bridge permission setup worked, whether Wireless Debugging could be turned on/off without an active ADB transport, how Secure Local Shell behaved after Wireless Debugging was disabled, and which AI client you used.

Also share errors, confusing steps, missing features, usability ideas and anything you think should be improved. Real-world feedback from different manufacturers is especially useful.

Please do not post pairing codes, access tokens, private keys, personal files or unredacted logs containing credentials. Describe the issue or share a redacted error instead.