AI Termux WADB Toolkit 讓兼容的 AI 助手使用 Android Termux 環境

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.

The system in one picture

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.

These are separate layers:

• MCP connects the AI client to Desktop Commander and its authorised tools.
• Termux is the command-line environment where the Toolkit and other programs run.
• Wireless ADB is Android's authenticated network debugging connection.
• Secure Local Shell is a separate authenticated, loopback-only Android shell route that can continue to work after Wireless Debugging is turned off, once it has been set up.
• WADB Bridge is the Android companion component, not the AI model, MCP server or Termux replacement.

What apps and components are involved?

Termux — the working environment

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.

Its main install locations are:

/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

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 — the AI connection on the phone

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

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.

AI Termux WADB Toolkit — the management layer

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 — the Android companion

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.

Termux:API — optional Android integration

There are two separate Termux:API pieces:

1. the Termux command package, installed with pkg install termux-api;
2. the compatible Termux:API Android companion app.

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.

Other underlying tools

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.

Which source components perform the work?

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.

Exact Android APIs, broadcasts and system mechanisms

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 Java class is com.jaskran.wadbbridge.WirelessDebugReceiver.
• It reads the setting with Settings.Global.getInt(contentResolver, "adb_wifi_enabled", -1).
• It changes the setting with Settings.Global.putInt(contentResolver, "adb_wifi_enabled", 1) to enable it or 0 to disable it, then reads the value back and returns the actual result.
• The Android manifest exposes the receiver but protects it with android.permission.WRITE_SECURE_SETTINGS.
• The two explicit broadcast actions are com.jaskran.wadbbridge.GET_WIRELESS_DEBUG and com.jaskran.wadbbridge.SET_WIRELESS_DEBUG.

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.

What does “initial setup” actually mean?

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.

1. Prepare Termux and shared storage

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

pkg update
pkg install nodejs npm
termux-setup-storage

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.

2. Install the Toolkit in Termux

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

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.

3. Start Desktop Commander and connect the AI

In Termux, start the phone-side service:

npx @wonderwhy-er/desktop-commander@0.3.1 remote

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.

4. Establish Wireless ADB trust and the Bridge permission once

Run:

ai-info
ai-info --connect

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

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

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.

Wireless ADB: turn it on and off without running ADB every time

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.

Direct commands:

wireless-debug-status
wireless-debug-on
wireless-debug-off

Or use the interactive Control Center with ai-info. Its Wireless ADB disconnect option offers two different actions:

1. Disconnect the current verified ADB transport only. Wireless Debugging stays ON, so it can reconnect later.
2. Turn Android Wireless Debugging OFF through WADB Bridge. This ends Wireless ADB but does not stop Desktop Commander MCP or Secure Local Shell.

Explicit command-line forms:

ai-info --disconnect-transport --confirm
ai-info --wireless-off --confirm

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.

Secure Local Shell: Android shell access while Wireless Debugging is off

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.

Enable or repair it with:

wadb-local-on
wadb-local-status
wadb-local-shell -c 'id'

Stop it with:

wadb-local-off --confirm

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.

Desktop Commander controls and recovery

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

• 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.

Optional local recovery watchdog

After the first successful Desktop Commander login:

wadb-mcp-recovery-setup
ai-info --recovery

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.

Optional GitHub recovery

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:

• a local read-only token for one private repository;
• an existing authenticated Termux GitHub CLI (gh) session;
• anonymous Git/curl access to a public control repository.

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.

What ai-info and the other Toolkit options do

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

Additional command families:

• Wireless ADB: wireless-adb-connect, adb-mdns-discover, wireless-debug-status, wireless-debug-on, wireless-debug-off.
• Bridge/bootstrap: wadb-bootstrap, cached APK synchronisation and Bridge readiness checks.
• Secure Local Shell: wadb-local-on, wadb-local-status, wadb-local-shell, wadb-local-off.
• MCP lifecycle: wadb-mcp-start, wadb-mcp-stop, wadb-mcp-restart, wadb-mcp-status, wadb-mcp-log, wadb-mcp-logout.
• Recovery: wadb-mcp-recovery-setup, wadb-mcp-recovery-disable, watchdog helpers and the Android Bridge recovery hand-off.
• GitHub fallback: wadb-mcp-github-config, wadb-mcp-github-test, wadb-mcp-github-sync.
• Device checks and integrity: phone-capabilities --details, wadb-integrity-check.

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

What can an AI actually do with it?

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.

Examples include:

• inspect a source-code project, search for a function, compare files and run tests;
• use Python or Node.js scripts to process data and generate reports;
• use Git to inspect a repository, create a branch or prepare changes;
• build a project when the required compiler, SDK and dependencies are installed;
• inspect APK metadata, manifests and resources with the relevant Android tools;
• organise accessible Downloads or project folders, create archives and save results;
• check Android properties and supported settings through the authorised shell route;
• inspect Wireless ADB, WADB Bridge, Secure Local Shell, MCP and recovery status;
• restart Desktop Commander while keeping its saved authorisation;
• turn Wireless Debugging off after setup without terminating the AI-to-Termux MCP session.

Example requests:

“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.

What it does not do

The Toolkit does not:

• install or provide an AI model;
• install Desktop Commander as part of the Toolkit package;
• bypass Android app sandboxing or grant unrestricted access to other apps' private data;
• make a non-rooted phone rooted;
• turn Wireless ADB pairing into a permanent or unauthenticated connection;
• guarantee that Android will never kill a background process;
• remove the AI provider's account, tool-call, usage or context limits;
• bundle every compiler, SDK, reverse-engineering program or file parser.

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.

Source and licence

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

Share your experience

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.