How to Use CleanYourTV: The Beginner’s Guide (Remove Ads and Bloatware From Your Android TV — No Root, No Cable)

CodexFuse Team · 2026-11-03T06:09:32.655Z · 12 min read min read

CleanYourTV is the free, open-source project that uses an AI coding agent to strip ads and bloatware from Android and Google TVs: this beginner’s guide covers eligibility, USB debugging, the prompt flow, the restore script, and version 3.3.

What Is CleanYourTV, Exactly?

CleanYourTV is a free, open-source project that uses an AI coding agent to strip ads and bloatware from Android TV and Google TV sets. You point the agent at your TV over your home Wi-Fi, it disables the manufacturer's preloaded packages through Android's developer tools, and then it builds you a small, clean, ad-free home screen to replace the stock launcher. Everything is reversible: nothing is ever uninstalled, so you can always switch the packages back on.

The project is the creation of developer Gathin (@gathint), published at github.com/Gathin23/cleanyourtv and released under the MIT license. It started on October 17, 2026, when Gathin handed Claude Code his parents' Xiaomi TV model over Wi-Fi; the agent found the TV, removed 25 Xiaomi packages, and wrote a new launcher from scratch — a post about it hit 8.6 million views, and the repo has since crossed 50,000 GitHub stars. If you want a gentler start that builds a disable plan before touching your TV, our companion CleanYourTV Studio tool walks through brand presets and safety checks — it is a plan-builder, not the upstream project itself, and this guide covers the real thing.

Does CleanYourTV Work on Your TV?

That is the first question to answer, because CleanYourTV only works on TVs that speak Android's developer protocol. If your TV is not on this list, the agent simply cannot reach it.

So the eligibility rule is simple: Android or Google TV gets the full treatment, Fire TV gets debloat only, and everything else is out. Check the repo's supported-TV list for your exact model before you begin — there is one folder of examples per model, and a tested list for your set makes the whole process safer.

What You Need Before You Start

The short answer: a computer on the same Wi-Fi as the TV, Python 3, and about fifteen minutes. The agent does the skilled work — your job is to set the stage so it can connect.

You do not need a rooted TV, a USB cable, or any paid software. The project publishes no app in any app store — its official site is cleanyour.tv, and the README warns that similarly named domains are not theirs.

How Do You Run CleanYourTV?

Follow these five steps in order. A community walkthrough timed the whole thing at about fifteen minutes on a Xiaomi TV.

1. Turn on USB debugging on the TV. Go to Settings, then Device Preferences, then About, and press OK on Build seven times to unlock Developer options. Open Developer options and switch on USB debugging — enable Network (or ADB, or Wireless) debugging too if your set shows that option.
2. Clone the repo and open it in your agent. Run git clone https://github.com/Gathin23/cleanyourtv on your computer, then open that folder inside your coding agent.
3. Paste the prompt with your TV model. Copy the contents of PROMPT.md into the agent and tell it your exact TV model. The agent does the rest: it asks which apps you actually use, what order you want them in the dock, and whether to keep things like the voice assistant, Chromecast, and software updates.
4. Accept the debugging prompt on the TV. When the agent first connects, your TV shows an "Allow USB debugging?" dialog. Accept it. From here the agent backs up your current package list, disables the junk in small batches, and shows its work.
5. Let it build and install the launcher. The agent compiles the clean launcher on your computer and installs it with TV_HOST=<your-tv-ip> launcher/build-and-install.sh. It makes the new launcher the default Home and rolls back if the switch does not land.

That is the whole flow: unlock debugging, paste the prompt, answer the agent's checklist, and let it work. No root, no cable, no command-line wizardry from you.

What Changes When the Agent Finishes?

Two things, in this order: first a backup, then the disable pass, then the new home screen. The agent runs tools/disable.sh, which writes a record of your TV's current state to ~/.cleanyourtv/ before changing anything. Only then does it disable the manufacturer's telemetry, ad services, content rows, and preloaded apps with pm disable-user — Android's own "turn this package off for the user" command. Nothing is uninstalled, which is why everything can be reversed.

Next comes the launcher: a tiny native app built from source on your computer, roughly 572 KB, written in plain Java, with no network permission and no background services, designed to run on TVs with as little as 1 GB of RAM. The build script only disables a stock launcher it recognizes — Google's leanback or TV launchers, or Xiaomi's TV Home and PatchWall — and it refuses to leave the TV without a working Home app. The result is a home screen that shows only your apps, in your order, with no sponsored rows. If you later want your own media server on the clean set, our Jellyfin beginner guide covers setting one up.

How Do You Undo Anything It Changed?

You run the one-line restore script, and everything comes back. Because the agent only disabled packages instead of deleting them, reversal is a single command: TV_HOST=<your-tv-ip> tools/restore.sh examples/<your-tv>/debloat.txt — on Google TV sets you pass the stock launcher's package name as a third argument. No computer? Your TV's own Settings, then Apps screen can re-enable any package by hand. That restore-first design is also why the agent works in small batches: a community safety guide warns that disabling the wrong package can break a TV — a Google TV setup package nicknamed "setupwraith" can crash-loop the home screen if disabled, and one reported case (issue 884) left a Mi TV Stick unable to boot after a bad list. Work in small batches, keep the restore script, and you always have a way back.

Why Must You Turn Debugging Off When You Are Done?

Because network ADB is an unencrypted door into your TV, listening on port 5555. While debugging is on, any device on your home network can reach the TV over ADB — and on firmware where the ro.adb.secure flag is off, a stranger on your LAN gets a shell without any approval. The README's own rule is unambiguous: when you are finished, turn off USB, Network, and Wireless debugging, revoke the debugging authorizations, reboot the TV, and confirm the port is closed by running python3 tools/adb-closed.py <your-tv-ip> — it must report that the port is closed. Never forward the ADB port on your router; the project's remote-access guide routes off-network runs through Tailscale instead.

What Did Versions 3.0 Through 3.3 Add?

The version history is a good way to see how fast this project moves — the current release is v3.3, as of early November 2026, just days after v3.2.

Between releases the repo keeps growing — the README's live badge currently counts 427 models and 111 brands — and the project's own story notes 412 press articles from 54 countries and a week as GitHub's number-one trending repository in late October 2026.

The add-on system is where the project gets playful: 31 optional modules live in the addons/ folder and are managed with tools/manage.py, with a gallery at cleanyour.tv/addons. Examples include Home Assistant cards for lights and locks, a pause-Pi-hole-from-the-couch card, remote-button remapping, a Game Day card, a weather card, and a Nepali Calendar card. The Pi-hole card hooks straight into the what is a homelab world of self-hosted network services — your TV can talk to your own DNS server.

What Can Go Wrong — and How Do You Avoid It?

Honestly, four things, all preventable. First, the agent can disable something your TV needs. The project's own docs name the danger: disabling Google TV's setup package (setupwraith) can take the home screen with it, and one community report describes a Mi TV Stick that never booted again after a bad package list. The defense is the safety spine of this whole guide: small batches, the backup-first rule, and the one-line restore script. If the worst happens, a factory reset from the recovery menu is the last resort.

Second, firmware updates re-enable the junk. TV makers push updates that quietly switch the disabled packages back on. The project ships tools/check.py --fix to re-apply your disable list after an update — plan to run it whenever your TV updates.

Third, a clean home screen does not mean ad-free apps. Removing the sponsored rows fixes the home screen, but ads inside streaming apps are a different battle. The project's honest answer is optional private DNS through AdGuard DNS — which, as the README notes, sees every DNS query you make and still does not block YouTube ads.

Fourth, no laptop, no agent. If you have no computer handy, the community has built independent companion apps — TidyTV (on Google Play), CleanMyTV (for Mac and Windows), plus a Clean Your TV app and Tellyscope — which do a version of the debloat without the agent flow. They are not affiliated with the project, so check their reviews first.

Sources

CleanYourTV repository and README (github.com/Gathin23/cleanyourtv — repo created October 17, 2026; page fetched November 3, 2026): star count snapshot, author Gathin (@gathint), the October 17 origin story, how-it-works arc, requirements, the backup-first and restore rules, the port-5555 warning, the home-guard launcher rules, the eligibility matrix, and the honest caveats. CleanYourTV releases page (fetched November 3, 2026): v3.3 as latest release with its model, brand, language, add-on, and theme counts, the TCL G08 fix, and the three-day contributor numbers. CleanYourTV LICENSE file (fetched November 3, 2026): MIT license text. Wccftech, "CleanYourTV 3.0 lets you remove ads and bloatware from Android and Google TVs, now supports 300 models" (published October 26, 2026, updated October 27, 2026 — Sebastian Castellanos): v3.0 figures and star count. Medium/@dedupedai, "How to Strip the Ads Off an Android or Google TV in 15 Minutes With a Coding Agent" (published October 24, 2026 — Deduped): the 15-minute walkthrough arc and the Fire TV debloat-only behavior. DevelopersDigest, "CleanYourTV Claude Code Debloat Android TV Safe Guide 2026" (last updated October 25, 2026): the safety-first angle, the setupwraith warning, issue 884, the port-5555 and ro.adb.secure=0 warning, and the TechCrunch coverage note. Settl.fyi, "CleanYourTV" (crawled November 3, 2026; internal anchor cites 5,830 stars on October 20, 2026): PROMPT.md excerpts including the backup-first rule, the port-5555 plaintext warning, and the restore line. LowYat forum, CleanYourTV topic (published October 22, 2026, updated October 31, 2026 — sitescope): the Antigravity-on-Windows community guide, the "turn debugging off when done" rule, and the keep-the-backup guidance.

Frequently Asked Questions

Is CleanYourTV safe?

It is as safe as its backup-first design: the disable script records your TV's state before changing anything, packages are only disabled (never deleted), and a one-line restore script brings everything back. The real risks are disabling a needed package — work in small batches — and leaving USB debugging on afterwards, which the project tells you to switch off immediately.

Does CleanYourTV work on Samsung or LG TVs?

No. Samsung's Tizen and LG's webOS do not support ADB, so the agent cannot connect to them. The project's showcase lists four community-built webOS ports, but those are separate efforts, not part of CleanYourTV.

Does CleanYourTV root your TV?

No. It never roots anything and nothing is uninstalled. The agent uses Android's built-in developer tools over Wi-Fi to disable packages for the current user — the same mechanism your TV's own settings use, fully reversible.

Do I need a computer to use CleanYourTV?

For the full agent flow, yes: a computer on the same Wi-Fi running Python 3, JDK 17 to 22, and a coding agent like Claude Code, Codex, Gemini CLI, or Antigravity CLI. If you have no computer, independent community apps like TidyTV and CleanMyTV offer a simpler debloat without the agent — they are not affiliated with the project.

What happens when my TV gets a firmware update?

Updates often re-enable the packages you disabled. The project ships a checker for exactly this: run tools/check.py --fix after any firmware update to re-apply your debloat list.