Android Ad Cleaner — What This Project Does

A tool that turns off ads, trending searches, news feeds, and marketing notifications built into Chinese Android phones (like OPPO, Xiaomi, Honor, vivo, OnePlus).

Core Approach

• No root, no bootloader unlock, no flashing — system updates still work normally.
• Only flips switches that the system and apps already expose in their own settings.
• Suspending ad packages (like com.opos.ads or com.miui.systemAdSolution) requires your explicit confirmation and can be undone with one command.
• Keeps useful features: search, home-screen cards, app store installs/updates, weather alerts, delivery reminders.

What It Targets

Category	Examples	How It's Handled
System ads	Personalized ads, ad tracking (OAID), smart recommendation services	Toggles in system settings
Hot searches & news	Search page trending lists, negative-screen news, browser feeds	Toggles in each app's settings; browser switched to simple homepage
Promotional slots	Store carousels, splash screens, floating activities, check-in rewards	Toggles in the store's "service management"
Marketing notifications	"Content & marketing," "promotions" notifications	Turned off per channel — order, delivery, and update notifications from the same app stay on
Ad components	com.opos.ads, com.miui.systemAdSolution	Suspended via pm suspend (needs your consent)
Quick apps	Mini-apps that launch when you tap an ad	Detected and disabled via quickapp off

What It Refuses to Do

• Won't uninstall or disable system apps (no pm uninstall, no pm disable-user).
• Won't modify the system partition or install modules.
• Won't accept any app's user agreement on your behalf — if a consent page appears, it cancels or defers.
• Won't capture screenshots of account pages or phone-number pages.

Four Ways to Use It

1. AI agent runs it for you — needs a computer, USB cable, and an AI tool that can execute commands.
2. Chat AI guides you — phone only; works with DeepSeek, Doubao, or ChatGPT.
3. Manual checklist — phone only; you follow step-by-step lists per brand.
4. Desktop client — Mac (Apple or Intel chip) or Windows 10/11; plug in the phone and click buttons. No Python or AI tools needed.

Desktop Client (v0.2.3)

• Available as a signed, notarized DMG for Mac (both Apple Silicon and Intel) and as an installer or portable ZIP for Windows.
• Workflow: connect phone → detect (model, OS version, scripts, quick apps, ad components) → choose what to turn off (marketing notifications per channel; service notifications unchecked by default) → run with progress bar and live logs → see results and get reminded to disable developer mode.
• Feedback button auto-attaches diagnostics (client version, phone model, OS version, recent logs — serial number replaced, no app list or notification content) and opens a GitHub issue.
• Known limitation: only works with Android devices connected via adb; does not support HarmonyOS NEXT (HDC).

Tested Devices

The project maintains device scripts — automated step-by-step instructions for specific phone models that record which app to open, which menu items to tap, which switches to flip, and which to leave alone. These are needed because settings pages vary by model and OS version.

Tested so far: Honor PNM-AN10 (MagicOS 10), OnePlus Ace 2 Pro (ColorOS 14), OPPO Find N6 / Find X10 Pro Max / Find X9 Ultra / Find N3 (ColorOS 16/17), Xiaomi 18 Pro Max (HyperOS 4.0), vivo X300 Ultra (OriginOS 6). Some are fully verified, some partially — the README marks each one's status.

If your phone isn't listed, you can write a script for it following the guide and submit a pull request.

Command-Line Flow

For users comfortable with the terminal, the full pipeline is:

pip3 install -r requirements.txt
python3 tool/run.py devices                 # list connected phones, check for scripts
python3 tool/run.py -s <serial> check        # read-only check
python3 tool/run.py -s <serial> backup       # snapshot before changes
python3 tool/run.py -s <serial> recipe       # run the device script
python3 tool/run.py -s <serial> chan-scan    # list marketing notification channels
python3 tool/run.py -s <serial> chan-off backups/<model>-<time>/channels.tsv
python3 tool/run.py -s <serial> quickapp     # detect quick apps; `quickapp off` disables
python3 tool/run.py -s <serial> finish       # wrap up, remind to disable developer mode
python3 tool/run.py -s <serial> dev-off --yes  # disable developer mode from the PC (last step)

Safety & Recovery

• Before changes, a backup snapshot is taken.
• Suspended packages and notification channels can each be restored with one command.
• In-app toggles are restored manually by following the checklist paths.
• The tool skips steps it can't find rather than clicking blindly.
• If a screen-reader service conflicts (e.g., GKD or auto-accounting apps), the tool detects it, retries once, and if still blocked, gives recovery steps and skips.

License

MIT. The project states it only uses settings publicly exposed by Android and vendor apps; users should back up before using and accept responsibility for results.

Project Structure (Key Parts)

• tool/run.py — main entry point
• tool/fast.py — engine for reading screens, finding menu entries, flipping switches (uses uiautomator2)
• recipes/<brand>-<model>/recipe.py — per-device automation scripts
• gui/ — desktop client (pywebview + PyInstaller)
• docs/ — tutorials, troubleshooting, restore guide, quick-app explainer
• prompts/ — ready-made prompts for chat AIs
• AGENTS.md — operating rules for AI agents