A repo that asks an AI coding agent to clean ads off your phone gained roughly 1,500 GitHub stars in two days. android-ad-cleaner (MIT licence) targets a very specific annoyance: the ads, trending-search lists, news feeds and marketing push notifications that ship inside the system software of many Chinese-brand Android phones. Its twist is the delivery method. Instead of a script you read and run, the README tells you to paste one sentence into Claude Code, Codex, Cursor or a similar agent and let it drive the phone over adb.
That makes it a useful, small, real example of what a mobile-device agent rulebook looks like, and of what can go wrong. This post covers what the tool does, how the agent instructions are built, which phones are actually tested, and the safety questions you should ask before connecting your own device.
TL;DR: what readers ask first #
| Question | Short answer |
|---|---|
| What does it do? | Turns off system ad personalisation, trending-search and feed recommendations, store promo slots and marketing notification channels |
| Does it need root? | No. No root, no boot unlock, no flashing, per the README |
| Is it free? | Yes, MIT licence. A desktop client for Mac and Windows is also offered |
| Does it need an AI agent? | No. There are four routes: agent, chat AI guiding you by hand, manual checklists, or the desktop app |
| Which phones? | Honor and Xiaomi models marked tested; OnePlus and OPPO partly; several still pending. Native HarmonyOS is unsupported |
| Can I undo it? | Backups, plus restore commands for suspended packages and channels |
| Main risk? | You grant an agent USB debugging; some steps rely on unverified model-specific screens |
What is android-ad-cleaner? #
The repository description, translated, reads: turn off the ads, trending searches, content recommendations and marketing pushes in Chinese Android phone systems, with no root, reversible, and with one-click execution by an AI agent. The latest tagged release at the time of writing is v0.2.3 (October 25, 2026), and the repo shows 45 commits, about 131 forks and a topic list that includes adb, ai-agent, coloros, hyperos, magicos and originos.
The README splits what it handles into categories:
- System ads: personalised ads, ad tracking (the OAID advertising identifier) and smart recommendation services, handled through the system settings switches.
- Trending searches and feeds: the hot-search list in the pull-down search, the news card on the minus-one screen, and browser feeds, handled through each app's own settings.
- Promo slots: carousels, splash ads, floating activity buttons and check-in rewards in the phone's app store, switched off in the store's service-management page.
- Marketing notifications: per-channel switches such as "content and marketing" or "offers", while keeping order, delivery and update alerts.
- Ad components: packages such as
com.opos.adsorcom.miui.systemAdSolution, suspended withpm suspend, only with the owner's consent. - Quick apps: the "instant mini-programs" that open from ads, detected and switched off.
Features the maintainer deliberately keeps include search, the minus-one screen cards, app store installs and updates, weather warnings and parcel reminders. The tool does not uninstall or disable system apps, does not touch the system partition and does not accept any app's user agreement on your behalf.
How the agent route works #
The agent route is the interesting part for anyone building with coding agents. The README's opener is a single instruction you copy to your agent: clone the repository, read AGENTS.md, then remove ads from the phone connected to the computer, telling the user what will change before each step.
The tool works through adb, Android's standard debug bridge, plus uiautomator2 for reading the screen and tapping switches. The repo's AGENTS.md is the real product: a 154-line operating manual for an agent. Its standard flow, as written, runs in numbered steps:
run.py devicesto find the phone, with prompts for USB authorisation if the status is unauthorized.run.py check, a read-only inspection of lock state, model-script match and ad packages.run.py backupto snapshot settings into abackups/folder before any change.run.py recipe, which replays a per-model script of which app to open and which switches to flip. Models without a script fall back to checklists.chan-scan, a read-only listing of open marketing notification channels, which the agent edits into a list the user approves beforechan-offruns and re-checks that zero channels remain on.quickappdetection, then a question to the user about suspending ad packages.finish, followed by a reminder to switch developer mode off.
The agent is meant to report in plain language: what was turned off, what could not be, which packages were suspended and how to restore them. For failures it can open a GitHub issue with the model, system version and a log with serial numbers redacted, after asking the user.
The rulebook is the safety layer
A green key fits a narrow opening in a fence, showing how the android-ad-cleaner AGENTS.md rulebook limits what an agent may change
The strongest part of the repo is how explicit the constraints are. A few of the hard rules in AGENTS.md, paraphrased:
- Every adb command carries
-s <serial>, because a computer may also be connected to a TV or an emulator. - Prefer in-app switches. Suspend packages only with consent, never
pm uninstallorpm disable-user. - Do not agree to user agreements, privacy policies or permission prompts. Tap "cancel", "later" or "don't allow".
- Do not bypass the lock screen; ask the user to unlock.
- Do not screenshot account or phone-number pages, and delete any that were captured.
- For switches phrased as protection, such as "limit ad tracking", turning them on is the protective action, so the engine flips them to on.
- Never suspend the pull-down search, minus-one screen or app store;
run.pyrefuses.
That is a good template if you write your own device-control AGENTS.md: scope every command to a target, name the irreversible actions you forbid, tell the agent when to stop and ask, and define what to say at the end. It echoes themes we covered in why frontier labs skip agent security basics and in Anthropic's work on agent monitors that fail attacks.
Which phones actually work #
This is where to be sceptical. The README's own table is candid, and it is worth reading before trusting the star count.
| Brand and model (as listed) | System | Status in the README |
|---|---|---|
| Honor PNM-AN10 | MagicOS 10 | Script tested, rerun in about 4 minutes; 26 notification channels |
| OnePlus Ace 2 Pro | ColorOS 14 | New in source: 3 personalisation and 6 store-promo switches changed and read back; partial |
| OPPO Find N6 | ColorOS 16 | Path tested, full run still awaiting verification |
| OPPO Find X9 Ultra, Find N3 | ColorOS 16 | Script pending, partial lists |
| Xiaomi 18 Pro Max | HyperOS | Passed a round before October 25; new compatibility changes need retest |
| vivo X300 Ultra | OriginOS 6 | Script added, whole run awaiting real-device check |
Two caveats stand out. First, settings pages differ by model and minor system version, so a script recorded on one phone can miss on another; when versions do not match, the engine switches to a safe mode that only flips named switches and skips what it cannot find. Second, the maintainer notes some apps relaunch ad services after suspension (observed on ColorOS 14 and older Xiaomi systems), so a suspend is not a guaranteed permanent stop. The tool reports partial completion instead of claiming everything is off.
Native HarmonyOS devices that use HDC rather than adb are not supported at all.
What the community is hitting #
The repo's changelog is itself a list of real-world failure modes, which is useful reading for anyone building phone agents. Recent entries mention a screen-reading service conflict (already registered) when another automation tool such as GKD or an auto-bookkeeping app holds the accessibility service, off-screen coordinates on foldables, an Honor screenshot size mismatch, vivo notification pages that only expose an app-level master switch (which the tool now skips rather than silencing the whole app), and a "find a photo spot" notification that older lists could wrongly turn off. Those are the kinds of edge cases that make a rulebook necessary rather than optional.
Risks and what to check first #
A green stylus placing a bead into a slot, like an agent flipping one switch at a time on a phone settings page
Treat this as you would any tool that asks for USB debugging.
- You are granting broad access. adb debugging can read and change a lot. Try a spare phone first, back up data, and switch developer mode off afterwards, as the tool itself reminds you.
- Terms of service and warranty. Switching off vendor-provided ad and recommendation features may conflict with a vendor's terms, and the repo's disclaimer says any consequences are the user's. The tool says it only touches settings that the system and apps expose.
- Agent mistakes. The repo's guardrails reduce harm, but an agent that misreads a screen can still flip the wrong switch. Ask it to show the planned list before each step, as the README suggests, and read the channel list yourself.
- Data exposure. If the agent runs in a cloud tool, screen text it reads is sent to that provider. The README says screenshots are avoided and account pages are never captured, but check your agent's privacy settings. We looked at similar concerns inAI agent privacy promises andApple's full-disk-access prompts for agents .
- Supply chain. You are cloning and running Python from a young repository with a signed Mac build but an unsigned Windows prompt ("More info, Run anyway"). Read the code or run it in a sandbox.
If you run agents against real devices or accounts, a policy layer that blocks dangerous actions before they happen is worth having; AgentBeam is the agent security platform from the explainx.ai team built for that.
Why it matters beyond ads #
The repo is a compact case study of where agent tooling is heading: tedious, vendor-specific, GUI-only chores handed to an agent, with a plain-text manual (AGENTS.md, plus CLAUDE.md and CODEBUDDY.md variants) taking the role a GUI wizard used to play. It also shows the cost: every device model needs its own recorded route, and the maintainer reports, test by test, how brittle screen-driven automation is when UI labels change. The same brittleness shows up in larger efforts such as Alibaba's open computer-use agent stack. For teams juggling several coding tools, running Claude Code, Codex and Cursor side by side is one way to compare how each follows a rulebook like this.
Try it safely #
- Read the README table and find your model and system version.
- Enable developer options and USB debugging on a spare or backed-up phone.
- Install
adband Python 3, thenpip3 install -r requirements.txt. - Run
python3 tool/run.py devices, thencheckandbackup, and read the output before going further. - If using an agent, give it the README opener and require it to show the planned changes before each step.
- When finished, run
finish, verify search, store and browser still work, and turn developer mode off.
You do not need an agent. The README also offers a desktop client (Mac Apple silicon and Intel, Windows installer and portable zip), a route where a chat AI such as DeepSeek or ChatGPT guides you tap by tap, and manual per-brand checklists.
Bottom line #
android-ad-cleaner is neither magic nor a major lab release; it is a fast-growing, honest, one-maintainer project whose most reusable asset is its rulebook. If you own one of the tested phones and are comfortable with adb, it can save an afternoon. If you do not, use it as a model for writing constrained, reversible instructions for your own device-control agents.
Specifications, supported models and release numbers reflect the repository as of October 26, 2026 and may change.