CleanYourTV: Debloat Android TV & Google TV

1. Project Overview

CleanYourTV is an open-source toolkit for Android TV and Google TV that removes preloaded bloatware, ads and telemetry over Wi-Fi and replaces the stock home screen with a lightweight, Apple TV-style launcher — with no root, no cable, nothing uninstalled, and a one-line restore.

2. Background & Positioning

Why it was created

Many smart TVs ship with preloaded apps, promotional content rows, ad services and background telemetry that slow down the device and clutter the home screen. CleanYourTV gives owners a safe, reversible way to take control of their own TV using only the settings the owner is already allowed to change (built-in ADB debugging).

How it differs from similar projects

Reversible by design: apps are disabled with pm disable-user, never uninstalled, and a recorded snapshot makes restore a single command.
Device-aware: the debloat list differs per brand, so a coding assistant inspects your specific TV and asks before changing anything.
Bundled launcher: debloating and a replacement home screen come in one project (about 497 KB, plain Java, runs on TVs with 1 GB of RAM).
Community-tested lists: the examples/ folder holds per-model debloat lists contributed by users (170+ models).

3. Feature Categories

🧹 Debloat & Ad Removal

Disables telemetry, ad services, content rows and preloaded apps without root.

Backup of the installed package list and settings
pm disable-user based disabling (nothing is uninstalled)
Safety check that refuses to disable the active Home app without a replacement
check.py to detect packages restored by firmware updates (--fix reapplies)
One-line restore from a recorded state

📺 Lightweight Launcher

A fast, minimal replacement home screen for Android TV and Google TV.

Black background with a favourites dock and app grid
Top shelf that names the focused app
Glass-style focus highlight and frosted buttons (Inputs, network, Settings)
Clock screensaver with optional CPU, memory and storage stats
25 languages, including a mirrored right-to-left layout

🎨 Themes & Customization

Personalize the look without rebuilding the launcher.

Configurable colours, wallpapers, dock and column count
Bundled themes such as default, aurora and six-columns
Apply a theme with tools/theme.sh
Remote-key remapping and app library (optional)

🧩 Add-ons & Module Cards

Extend the launcher with optional apps.

Other apps can add tiles, only with user approval
Add-ons live in the addons/ folder
Companion pages at cleanyour.tv for apps and add-ons

🔒 Privacy & Safety Tools

Understand and reduce what your TV does in the background.

privacy.py reports voice, ACR and telemetry candidates with evidence
adb-closed.py confirms the network ADB port is closed afterwards
Optional AdGuard DNS setup for in-app ad blocking via Private DNS
Optional Tailscale for secure remote management

🛠️ Developer & Diagnostics Tools

Utilities for maintainers and contributors.

tv.py pure-Python ADB client and probe
bench.py, trace.py and screendiff.py for performance and visual checks
manage.py for device management
A test suite in tests/

4. Key Highlights

No root, no cable: works over Wi-Fi using the TV's built-in network ADB debugging.
Fully reversible: nothing is uninstalled, and a snapshot-based restore returns the TV to its prior state.
AI-assisted workflow: paste PROMPT.md into a coding assistant such as Claude Code, Codex or Gemini CLI, and it guides the whole cleanup in about fifteen minutes.
Tiny launcher: about 497 KB, written in plain Java, targeting Android 8.0 (API 26) and above.
Broad community coverage: tested debloat lists for 170+ TV models across brands such as TCL, Sony, Xiaomi and Philips.
Global by default: 25 interface languages, with README translations in Japanese, Vietnamese and Simplified Chinese.

5. Use Cases by Role

General users and TV owners: get a faster, cleaner home screen without technical risk.
General developers: study a compact native Android TV launcher and a pure-Python ADB client.
DevOps / SRE: manage fleets of TVs or kiosks remotely using the scripts and Tailscale.
Security engineers: audit telemetry, voice and ACR candidates with privacy.py and verify ADB is closed afterwards.
Project managers / integrators: prepare consistent, ad-free signage or hospitality displays using shared debloat lists.

6. Getting Started

Find what you need

Browse the per-model lists in examples/ and the guides in docs/, or visit https://cleanyour.tv.

Install / integrate

On the TV, enable Developer options and USB debugging, and keep it on the same Wi-Fi as your computer.
Paste PROMPT.md into a coding assistant and enter your TV model, or run the manual commands:

git clone https://github.com/Gathin23/cleanyourtv.git
cd cleanyourtv
python3 -m venv tools/venv && tools/venv/bin/pip install -r tools/requirements.txt
export TV_HOST=192.168.1.50
tools/venv/bin/python -I tools/tv.py --probe
tools/disable.sh examples/<model>/debloat.txt
TV_HOST=192.168.1.50 launcher/build-and-install.sh
tools/theme.sh themes/aurora

To undo everything:

tools/restore.sh examples/<model>/debloat.txt

A community-built Android app can also do the cleanup from a phone without a computer.

Contribute

Add a tested debloat list for your TV model to examples/, then read CONTRIBUTING.md and open a pull request: https://github.com/Gathin23/cleanyourtv/blob/main/CONTRIBUTING.md

7. Project Structure

cleanyourtv/
├── addons/        # optional add-on apps shown as module cards
├── docs/          # guides, specs, troubleshooting, device notes
├── examples/      # per-model debloat lists
├── launcher/      # Android launcher source and build scripts
├── themes/        # theme folders (default, aurora, six-columns, ...)
├── tools/         # Python/shell utilities (tv.py, disable.sh, restore.sh, check.py, privacy.py)
├── tests/         # test suite
├── PROMPT.md      # prompt for coding-assistant-driven setup
├── CONTRIBUTING.md
├── SECURITY.md
└── LICENSE

8. Related Ecosystem

Android Debug Bridge (ADB): the mechanism used to control the TV.
Coding assistants: Claude Code, Codex and Gemini CLI can drive the guided setup.
Build toolchain: JDK 17 and Android SDK platform 34 with build-tools 34.0.0 for the launcher.
Optional services: Tailscale (remote management) and AdGuard DNS (ad blocking).
Related platforms: Fire TV is supported for debloat only; Samsung (Tizen) and LG (webOS) are different systems covered by separate notes.

9. License

✅ Use, copy, modify and distribute the software, including commercially, under the terms of the MIT license (as stated in the project README)
✅ Include it in your own projects with the license notice preserved
❌ No warranty is provided; the authors are not liable for damages
❌ Not affiliated with or endorsed by any TV manufacturer
ℹ️ GitHub reports the license as unrecognized (NOASSERTION); check the LICENSE file in the repository
ℹ️ The Outfit font is under the SIL Open Font License

10. FAQ

Q: Is it safe, and can I undo it?
A: Apps are only disabled, never uninstalled. Run tools/restore.sh examples/<model>/debloat.txt to revert.

Q: Does it work on Fire TV, Samsung or LG TVs?
A: Fire TV supports debloat only. Samsung (Tizen) and LG (webOS) are different systems and are not directly supported.

Q: Do firmware updates undo the changes?
A: Updates can re-enable packages. Run check.py to see what changed, and add --fix to reapply your list.

Q: Can I do this without a computer?
A: Yes, a community-built Android app performs the same cleanup from a phone.

Q: Should I leave ADB on afterwards?
A: No. Network ADB is unencrypted on port 5555; turn it off when finished and verify with adb-closed.py.

11. Quick Links

Repository: https://github.com/Gathin23/cleanyourtv
Website: https://cleanyour.tv
Contributing guide: https://github.com/Gathin23/cleanyourtv/blob/main/CONTRIBUTING.md
Discussions: https://github.com/Gathin23/cleanyourtv/discussions
Security policy: https://github.com/Gathin23/cleanyourtv/security

12. Summary

CleanYourTV gives TV owners a safe, reversible way to remove bloat, ads and telemetry and to install a fast, clean launcher, all over Wi-Fi without root. It suits anyone with an Android TV or Google TV who wants a faster, quieter home screen, as well as developers and security engineers who want a compact, well-documented codebase to learn from or extend.