Gathin23/cleanyourtv

Maintainer? Show your league in your README

Card: your league's emblem, from Copper to Legendary

[![bestofgithub](https://bestofgithub.dev/badge/Gathin23/cleanyourtv.svg?style=card)](https://bestofgithub.dev/repo/Gathin23/cleanyourtv)

Flat: fits beside your other badges

[![bestofgithub](https://bestofgithub.dev/badge/Gathin23/cleanyourtv.svg)](https://bestofgithub.dev/repo/Gathin23/cleanyourtv)

Loading README…

You have	Go to
An Android TV or Google TV	Quick start: a coding assistant does the work in about fifteen minutes.
A Samsung, LG, Roku, Vizio or Hisense VIDAA TV	cleanyour.tv/not-android: CleanYourTV can't run there, but you can turn off the tracking with your remote.
Only an Android phone	The community-built Clean Your TV app: no laptop, no coding agent.
Want to see it first	What you get: screenshots of the new home screen.

Step	What happens
Back up	The list of installed packages and settings.
Disable	The manufacturer's telemetry, ad services, content rows and preloaded junk, with `pm disable-user`. Nothing is uninstalled, so a restore script can undo every step.
Install	A small native launcher, made the default home screen.

You have	Do this
A computer	Use the prompt with a coding assistant: the three steps below.
A computer, no coding assistant	Run the three steps yourself: the commands are in Doing it by hand.
Only an Android phone	Use the community-built Clean Your TV app by @udhaykumarbala: connect, analyse, clean, in about five minutes. No laptop, no coding agent.

Where	What to do
1. On the TV	Settings → Device Preferences → About → press OK on Build seven times → back → Developer options → USB debugging on. If you see a Network or ADB debugging toggle, turn that on too. Keep the TV on.
2. On your computer	Clone the repo and open that folder in your assistant (`git clone https://github.com/Gathin23/cleanyourtv`), then paste `PROMPT.md` and fill in your TV model.
3. Follow along	Accept "Allow USB debugging?" on the TV, then answer the checklist: which apps you use, the dock size and app order, whether to keep the voice assistant, Chromecast and updates.

Part	What it looks like
A pitch-black home	A dock of your four favourite apps in a rounded band, where Apple TV puts it.
A top shelf	Names the focused app in large type, with an ambient glow in a colour taken from its artwork.
The rest of your apps in a grid	Slides up when you press Down.
One floating glass highlight	Springs from tile to tile. The focused tile lifts and shows its name.
Three frosted buttons	Inputs (HDMI ports under the names you gave them in the TV's settings, AV, Live TV), Wi-Fi or Ethernet with the network name, Settings.
A greeting, a thin clock and the date	In Outfit, and a matching Clock screensaver. Set `show_stats` in config or a theme for one line under the clock: CPU, free memory and free storage. It stays off unless you turn it on, and it refreshes only while Home is on screen.
Themes and module cards	Themes change colours, wallpaper, dock and columns without a rebuild, and module cards let other apps plug a tile in, only with your say-so.

Gathin23/cleanyourtv

Start here

How it works

Quick start

What you get

Supported TVs

Doing it by hand

The microphone, and what can be said about it

The launcher

Restoring your TV

After a firmware update

When something goes wrong

Questions people ask

The story

Contributing

Contact

Legal

Licence



Top shelf and ambient glow	Inputs: HDMI with connection state, AV, Live TV

The grid, one glass highlight, the tile's name	Clock screensaver, drifts so nothing burns in

Aurora theme, pushed with `tools/theme.sh`	Six columns and a six-app dock, same launcher

With `tile_menu`, hold OK on a tile, Move: arrows carry it, Back puts it down	App library: one press puts a removed app back on Home

Platform	What works
Android TV, Google TV	The debloat and the launcher.
Fire TV	The debloat half only, since Fire OS will not hand Home to a third-party launcher. And on the 2015 Fire TV Box (Fire OS 5) even that half fails: every `pm` route is refused.
A few China-market TCL sets	They refuse to install any launcher at all; their lists say so in the header.
Samsung (Tizen), LG (webOS), Roku, Vizio, Hisense VIDAA	Not supported (no ADB). Turn off the tracking instead: cleanyour.tv/not-android. See SHOWCASE.md for four webOS ports, and docs/devices/samsung-tizen.md for what a 2021 Samsung set answers over Wi-Fi (no ADB, so no `pm disable-user`) if you are weighing a Tizen port.


TCL · 79	Sony · 42	Xiaomi · 36	Philips · 21	Skyworth · 15	Hisense · 14
Amazon Fire TV · 9	SHARP · 8	BenQ · 6	JVC · 6	Panasonic · 6	OnePlus · 4
Thomson · 4	Acer · 3	Google · 3	Grundig · 3	Haier · 3	Motorola · 3
NVIDIA Shield · 3	RCA · 3	Redmi · 3	Toshiba · 3	Vu · 3	CHiQ · 2
EKO · 2	FFalcon · 2	Hitachi · 2	Insignia Fire TV · 2	Kalley · 2	Kogan · 2

You need	For
Python 3 (any 3.x)	The tools. The venv command below installs what they import.
JDK 17 through 22 (a full JDK, including `jlink`) and Android SDK platform 34 with build-tools 34.0.0 or any newer 34.x	Building the launcher. JDK 23 and newer stops Gradle 8.9. Platform 34 is the one the build reads; a newer platform does not replace it. On macOS, when none of these is installed: `brew install openjdk@17 android-commandlinetools`, then `sdkmanager "platforms;android-34" "build-tools;34.0.0"`. On Linux the install script looks in `~/Android/Sdk` and for `java` on your PATH.

Tool	What it does
`tools/tv.py`	Pure-Python ADB client: shell, batch, push, pull, reboot, and screenshots, optionally pressing remote keys first. Works where the stock `adb` binary is blocked. Optional paired Google ADB backend for encrypted Wireless debugging.
`tools/docker-build.sh`	Builds the launcher or an add-on in Docker (JDK 17, Android SDK 34), so this computer needs nothing but Docker. Install the result with `SKIP_BUILD=1`. Guide.
`tools/b64push.py`	Uploads large files such as APKs in base64 chunks and verifies the checksum.
`tools/relay.py`	Forwards a local port to the TV's ADB port, for assistants whose sandbox can't reach your network. Listens on this computer only. Guide.
`tools/disable.sh`, `restore.sh`	Apply or undo a debloat list, the undo from the state recorded before the change.
`tools/recovery.py`	Writes the record `disable.sh` needs to undo itself, and prints the restore batch.
`tools/check.py`	Compares the TV with the list that was applied, for what a firmware update undid; `--fix` puts it back.
`tools/adb-closed.py`	Checks that the TV's network ADB port is closed once debugging is off: exits 0 when the TV refuses the connection, 1 while it is still open, 2 when nothing answered or the check itself could not run. No `nc` needed.
`tools/philips-api.py`	Philips only: checks that the JointSpace control API Home Assistant uses still answers, before and after a debloat (`tools/venv/bin/python -I tools/philips-api.py <tv ip>`). Port 1926 over HTTPS first, then 1925; reads only what answers without pairing.
`tools/privacy.py`	Audits the TV for voice, ACR and telemetry candidates and prints the evidence for each; `--write` turns the findings into a list `disable.sh` and `restore.sh` already understand.
`tools/theme.sh`, `theme_restart.py`	Push a folder from `themes/` to the launcher and restart Home.
`tools/manage.py`	List every add-on, theme and switch with its screenshot, see what is on the TV, and install, update or remove one by running its creator's own script.
`tools/bench.py`	Measures the launcher that answers HOME: key latency, how far the focus moved, janky frames, cold start, return to Home, and the idle CPU and PSS it costs. Changes nothing on the TV and writes the raw per-key numbers to JSON; no extra install.
`tools/trace.py`, `trace_report.py`	Records Perfetto traces of the launcher (return to Home, cold start, D-pad) and reports where its time goes, per run and before against after. Optional: needs `requirements-perf.txt`. Guide.
`tools/flamechart.py`	Draws a before/after flame chart from those traces, for a pull request: one lane per thread on a shared time scale, the work a change targets in magenta with its total. Optional, like the trace tools. Guide.
`tools/screendiff.py`	Compares a before and an after screenshot pixel by pixel, leaving out the clock or anything you mask, and writes the pair with your Wi-Fi name blurred. Optional, like the trace tools. Guide.
`tools/race_calendar.py`	Writes this season's F1 calendar into a theme for race-weekend mode, from the free Jolpica API.
`launcher/build-and-install.sh`	Builds a shrunk release (about 572 KB), installs it, switches Home, and rolls back if Home does not land on it.

What	How it works
Configure	Dock order, hidden apps, Live TV app, 4 to 7 tiles per row, reduced motion. All in `config.xml`
Settings on the TV	Hold OK on Settings for launcher settings. Optional `launcher_settings_button` makes a normal click open them directly; TV settings remain on the settings page and their app tile.
Themes	Background, wallpaper and layout from a `config.json` pushed over Wi-Fi, no rebuild. fourteen ship in `themes/`, the built-in `default/` included
31 languages	Follows the TV's language, with a fully mirrored right-to-left layout for Hebrew
App library	Optional: browse every installed app and add or remove Home shortcuts. See the app library guide
Tile menu	Optional (`tile_menu`): hold OK on a tile for Move, Remove from Home and App info. Off, holding OK opens App info
Module cards	Any TV app can offer its own tile; you approve each one once. See `docs/modules.md`
Add-ons	Optional apps that plug in as module cards, kept in `addons/` and never built into the launcher
Clock screensaver	A drifting clock over the glow, so nothing burns in
Remote keys	Keeps the Input, YouTube and gear buttons working after the stock launcher is gone

What	How
A record comes first	Before `tools/disable.sh` changes anything it writes down what the TV looked like, in `~/.cleanyourtv/`.
Restore replays it	A package you had disabled yourself stays disabled, and Home goes back to the component that owned it.
The launcher stays installed	Remove it from the TV's Settings → Apps if you want it gone.
No computer?	If the TV is unreachable, its own Settings → Apps page can re-enable packages too.

How to help	What it means
Your TV's debloat list	The most useful one: the next person with that model skips the discovery.
Launcher and prompt	Launcher improvements and sharper prompt wording are welcome too.
Built something on top?	A launcher, a port, a theme: add it to SHOWCASE.md, where a hundred and sixty-nine projects already live, sorted into home screens, forks, add-ons, tools and other platforms, with an index by TV brand.

For	Where
Questions about your TV	GitHub Discussions
Press and queries	hello@itsgathin.com
Security issues	Report them privately through the Security tab, see `SECURITY.md`