cleanmytv README

The project's README from github.com/wingedpanther/cleanmytv. As one markdown file: README.md.

CleanMyTV

A free Mac, Windows and Linux app that cleans up your Android TV over Wi-Fi. It switches off the preinstalled bloat and puts in CleanMyTV Home, an ad-free home screen you set up from your computer. You don't need Python, Java, Android Studio or adb.

The per-TV cleanup lists come from cleanyourtv by @gathint. Thanks, Gathin.

New to this? The user guide walks every step at TV-owner pace, including rollback and troubleshooting, and the known-devices table shows what the bundled lists cover per model. This README is the technical overview.

Questions, help and home-screen setups: join the CleanMyTV Discord. Bugs and feature requests go to GitHub issues.

New in 0.12.0

New in 0.11.0

New in 0.10.0

The big one: CleanMyTV Home can now be set up from the TV itself. Turn on Edit on the TV in the desktop app once, and a Customize icon in Home's top bar opens an editor you drive with the remote.

New in 0.9.0

New in 0.8.0

New in 0.7.2

New in 0.7.1

New in 0.7.0

https://github.com/user-attachments/assets/4e3eb18a-d196-4a51-8d0e-93ce98e11913

Download and install

Get the latest version from Releases:

Computer File
Mac with Apple silicon (M1 and later) CleanMyTV-<version>-arm64.dmg
Mac with Intel CleanMyTV-<version>.dmg
Windows 10 or 11 CleanMyTV-Setup-<version>.exe
Linux (64-bit) CleanMyTV-<version>.AppImage

Macs need macOS 13 Ventura or newer, and Windows needs Windows 10 or 11 on a 64-bit PC. The app asks GitHub for a newer version at most twice a day. On a Mac or Windows, Update now in the sidebar downloads it, checks it against the release's checksums and installs it; on Linux, download the new AppImage.

Each release also has CleanMyTV-Home-<version>.apk, the launcher on its own. Installed over CleanMyTV Home on the TV (with Downloader, for example), it keeps your settings.

The installers are not signed with a paid developer certificate, so your computer warns you the first time:

Before you start: on the TV

  1. Settings → Device Preferences → About (on some Google TVs: Settings → System → About).
  2. Press OK on Build (or Android TV OS build) seven times, until the TV says you are a developer.
  3. Back one screen → Developer options → turn on USB debugging. If you also see Network debugging or ADB debugging, turn that on too.
  4. Keep the TV on and on the same Wi-Fi as your computer.

Open CleanMyTV, find the TV and choose Allow when the TV asks. Tick Always allow from this computer to skip the question next time.

What it does

Step What happens
Clean & launch The guided path: applies the list that best matches your TV, then installs CleanMyTV Home.
Setup Checks the network, lists the TVs on your Wi-Fi by name (a phone with Wireless debugging on can show up too, and a scan finds older TVs with port 5555 open), connects, and waits while you press Allow on the TV. Google TVs that only offer Wireless debugging get a pairing form that fills in the ports when the TV's pairing screen opens, so you only type the code. With more than one known TV, it shows them with snapshot thumbnails to pick from.
Clean up Picks the upstream list that matches your TV's model, from 472 TVs and 129 brands. Every package shows its live state on the TV, and you choose what to disable. If your TV isn't listed, lists from its brand come first, and it offers the packages other TVs disable. You can add any package on the TV by name.
Home screen Installs or updates CleanMyTV Home and hands Home over. If Home doesn't land on it, it rolls back. If the app can't tell which app is the TV's own launcher, it asks. Tabs for layout, apps, rows and folders, look and wallpaper, widgets, music bars and remote buttons. See below.
TV extras Ad-blocking Private DNS, animation speed, an on-screen remote, reboot.
Finish Restarts the TV and checks the home screen comes back; if it doesn't, puts the stock launcher back. Then walks through switching debugging off, and checks that port 5555 is closed.
Setup, connected to a TV Clean up: the list that matches the TV, with each package's state

Nothing is uninstalled. Packages are switched off for your user, and Restore puts every package back the way it was before the first cleanup.

CleanMyTV Home

No ads. Your apps, your layout, the weather and what's playing. You change everything from your computer, and the TV shows it as you click. Or, with Edit on the TV switched on, from the TV with the remote: a Customize icon in the top bar opens the same settings, with a search to find them.

Shelf: the clock, weather and quick settings in the top corner, apps lower down Split: the clock and quick settings on the left, apps on the right
Shelf, the default Split
Rail: icons down the left edge that open with labels A folder open over the home screen
Rail, opened A folder

The Home screen step in the app, with a live preview of the TV

The Home screen step has eight tabs. Every change shows on the TV straight away. The Layout and Apps tabs have a live preview of the TV screen at the top.

Tab What you set
Overview Install or update Home, and how to use it. Give Home back to the stock launcher. Remove the old CleanYourTV launcher in one click if it's still on the TV. Take a snapshot of the TV screen.
Layout Three layouts: Shelf (the default), Split and Rail. Space above the apps. The now playing, dock, rows, folders and all apps sections, in any order, each one can be hidden. Quick-settings icons: Inputs, Wi-Fi, Bluetooth, Picture & sound, Apps, Screensaver, Search, Music bars, Quick settings, Themes, Fireplace and Settings. Icons the TV can't open are marked "not on this TV". Up to 6 apps as round icons in the same row, like a VPN. Dock and row tile sizes, apps per row, app names (always, focused app only, or off), clock and greeting. An idle screen: after a set time with no button pressed, only the wallpaper and a large clock show.
Apps, rows & folders Dock size, drag to reorder, hide apps, named rows and folders.
Look & wallpaper Themes: 28 looks with their own wallpaper art, three pictures each, saved to and loaded from .cmtvtheme files, and Put it back to undo them. Put the themes on the TV to switch them with the remote. App icons: banners, or every logo redrawn in Colour, Mono or Duotone, on wide, square, squircle or round tiles. Accent colour. Focus style (lift, glow, outline or none), with options to lean the tile toward the move, keep it in place while the row slides, and tint the background in the focused app's colour. Your own picture or Bing's picture of the day, darken, background colour, and the sunrise when it changes. A slideshow of up to 12 pictures. Make your own theme from a built-in one. The fireplace: put it on the TV, show it, make it the screensaver or put it behind Home, with its crackle and a turn-off timer.
Widgets Now playing: what any music or video app plays, with play, pause and next. Weather next to the clock for a town you pick, in °C or °F.
Music bars On or off; bars, mirrored or wave; accent, rainbow or white; peak dots, number of bars, height, opacity and sensitivity.
Remote buttons Find what a remote button sends, then give it a job in every app: open Settings, Inputs, an app, Home, Back, Quick settings, Themes, the fireplace, the theme's next picture, and more. Off until you turn it on. Only the buttons you map are touched. Power, volume and the mic button are usually handled before Android sees them. On Xiaomi TVs, one click makes the Mi button go Home.
App lock A 4 to 6 digit PIN, kept hashed on the TV, and the apps it locks. Optionally Settings, the Play Store and Quick settings too. An unlock lasts until the TV sleeps, 15 minutes, or until another app opens. Locked apps show a small lock on Home, or stay hidden. One switch turns it all off; the PIN and the list stay.

Your settings and wallpaper stay through updates and reboots. The app also keeps a copy on your computer: if CleanMyTV Home ever starts empty (after an uninstall or a factory reset), installing it puts the copy back. The wallpaper is also kept on the TV, so another computer can save the look with it. What the launcher can access is under Security and privacy.

CleanMyTV Home needs Android 9 (API 28) or newer.

Coming back to customise

Turn USB debugging on again and open the app. With one known TV, it reconnects to it. When CleanMyTV Home is already Home it opens the Home screen step, loaded with what is on the TV now. Switch debugging off again when you're done. If you didn't revoke the authorisations, there's no Allow prompt.

The app remembers each TV it has connected to. With more than one, it doesn't connect by itself: Setup shows the TVs with snapshot thumbnails, and you pick one. The sidebar shows the connected TV's thumbnail.

If the router gave the TV a new address, or another device now answers at the old one, the app says so and scans the network. You pick the TV from the list; the app does not log in to devices it found by itself.

Security and privacy

Found a security problem? Please report it privately through the repository's Security → Report a vulnerability page rather than in a public issue.

Credits and upstream

The per-TV cleanup lists are cleanyourtv's, by @gathint, shipped unchanged. CleanMyTV is an independent project, not part of cleanyourtv. Versions 0.1.x installed the CleanYourTV launcher (com.gathin.tvhome); since 0.2.0 the launcher is CleanMyTV Home, built from home/ in this repository, and the app can remove the old one.

The debloat side is a TypeScript port of upstream's tools/, and the launcher handover follows launcher/build-and-install.sh:

Upstream's themes aren't bundled. They are for upstream's launcher.

The "From Omarchy" home screen themes use the colours of the dark themes in Omarchy by David Heinemeier Hansson (MIT). Only the colours are used; the wallpapers are drawn by the app. Its licence ships in resources/licenses/.

The drawn app icons come from Simple Icons (CC0). Brand marks belong to their owners; Home only shows them to open the app they belong to.

The undo toast, the Apply button that changes as it works, the PIN boxes, the step bar, the loading rows and the ⌘K search follow components from EasyUI by Suraj Maurya (MIT), rewritten in plain CSS. Its licence ships in resources/licenses/.

The fireplace video and its crackle come from Pixabay under the Pixabay Content License, looped and re-encoded for the TV. They're downloaded from the fireplace-1 release when you put the fireplace on a TV, and aren't part of this repository.

The launcher APK

CleanMyTV Home lives in home/: Kotlin and Jetpack Compose for TV, package io.github.wingedpanther.cleanmytv.home. npm run home builds it into resources/home.apk, and resources/home.json records its version. The script uses JAVA_HOME and ANDROID_HOME if they are set. Otherwise it downloads JDK 17 and the Android SDK into .cytv-build/. Every build is signed with resources/signing/cleanmytv.jks, so each one installs over the others.

Develop

npm install
npm run sync                 # lists from the pinned upstream commit
npm run home                 # resources/home.apk (without JAVA_HOME/ANDROID_HOME, first run downloads the build tools)
npm run dev                  # the app, with hot reload
npx tsx scripts/fake-tv.ts   # a pretend TV on 127.0.0.1:5556 to try the app without one
UPSTREAM_DIR=<clone at the pinned commit> npm test
npm run dist:mac             # dist/*.dmg   (on a Mac)
npm run dist:win             # dist/*.exe   (on Windows, a Mac, or in CI)
npm run dist:linux           # dist/*.AppImage (on Linux or in CI)

To move to a newer upstream: review its changes, then node scripts/pin-upstream.mjs <commit sha>, npm run sync, and test on a TV. UPSTREAM_UNPINNED=1 lets sync use other content for a local trial.

.github/workflows/build.yml builds the APK on Linux and runs the tests on every push and pull request. Pushes to main and version tags also build the macOS, Windows and Linux installers; download them from the run's Artifacts. It runs with read-only repository permissions and actions pinned to commits.

Releasing

  1. Set the new version in package.json and commit it.
  2. Tag and push: git tag v0.3.0 && git push origin main v0.3.0.
  3. The workflow builds both installers and opens a draft release with them attached. Check it, then press Publish release.

The tag has to match the version in package.json, or the release step stops.

Help and community

Known limits

Licence

MIT, see LICENSE. The bundled debloat lists are from cleanyourtv by Gathin23, also MIT; its licence ships in resources/upstream/LICENSE. The Omarchy theme colours are MIT too; see resources/licenses/omarchy-LICENSE.txt.

cleanmytv (wingedpanther/cleanmytv)

Searching Database…

What is this?A free Mac and Windows app that cleans up your Android TV over Wi-Fi. It switches off preinstalled bloatware and installs CleanMyTV Home, an ad-free home screen you set up from your computer.
Is it a launcher or a cleaner?Both. It disables the preinstalled packages on your TV and replaces the home screen with its own launcher, CleanMyTV Home. Nothing is uninstalled, and the Restore step puts every package back.
How do I get it running?Download the installer from the Releases page. On the TV, open About, press Build seven times to enable developer mode, then turn on USB debugging. Keep the TV on the same Wi-Fi as your computer, open CleanMyTV, pick your TV and press Allow on the TV. Then run Clean & launch.
Do I need Python, Java or Android Studio first?No. You don't need Python, Java, Android Studio or adb installed on your computer. The only requirement on the TV side is developer mode with USB debugging enabled.
What should I watch out for?The installers are unsigned, so macOS and Windows will warn you the first time and need a manual OK. On a Mac you must allow local network access, or the app cannot reach the TV.
Which computers and TVs does it support?Macs with Apple silicon or Intel need macOS 13 Ventura or newer, and Windows 10 or 11 is supported too. CleanMyTV Home needs Android 9 (API 28) or newer on the TV.
Does it send anything off my network?Only to your TV, over ADB on port 5555 of your local network. Beyond that it contacts api.github.com at most twice a day to check for a newer version (it downloads nothing), dl.google.com only when you click Wireless debugging pairing, and www.bing.com only if you choose Bing's picture of the day.
What does CleanMyTV Home change on the TV?It replaces the stock home screen with an ad-free launcher with three layouts (Shelf, Split, Rail). You set the apps, rows, folders, wallpaper, themes, music bars and remote buttons from your computer, and the TV shows each change as you click.
Can I undo everything?Yes. Restore puts every disabled package back the way it was before the first cleanup. If CleanMyTV Home doesn't come back after a restart, the app puts the stock launcher back on its own.
Does it work with any Android TV?The cleanup lists cover 371 TVs from 100 brands. For an unlisted TV it starts with lists from its brand and suggests packages other TVs have disabled, and the known-devices table shows what is covered per model.
What is the fireplace feature?A looping log-fire video of about 11 MB that the app downloads once and sends to the TV. You can show it full screen, make it the screensaver or put it behind Home, and set it to turn off after 30 minutes, 1 or 2 hours.
Size
3.9 MB
Stars
651
Age
29d
Commits · 90 Days