tv-vibehack README

The project's README from github.com/Gathin23/tv-vibehack. As one markdown file: README.md.

tv-vibehack

Your TV, minus the ads.

Strip the bloatware from any Android TV or Google TV over Wi-Fi, and replace the ad-filled home screen with a clean launcher that looks like an Apple TV. No root, no cable, nothing uninstalled, and a one-line restore if you change your mind.

Before: stock Google TV home with a sponsored ad. After: the tv-vibehack launcher

It started as an afternoon fixing my parents' Mi TV, which showed them an advert before they could reach Netflix. The whole thing was done with Claude Code talking to the real TV, and the prompt that did it is in this repo so you can do the same with yours.

Table of contents

How it works

Android TVs have the same debug bridge as Android phones. Once you switch on USB debugging in the TV's developer options, the TV listens on your Wi-Fi and asks you once to allow your computer. After that, everything is standard Android tooling:

  1. Back up the list of installed packages and settings.
  2. 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.
  3. Install a small native launcher and make it the default home screen.

The bloat differs by brand, which is why the prompt asks your coding assistant to discover it on your TV and ask you before touching anything you might use.

Quick start

You need a computer on the same Wi-Fi as the TV and a coding assistant with shell access (Claude Code, or anything similar).

1. On the TV Settings → Device Preferences → About → press OK on Build seven times → go back → Developer options → turn on USB debugging. Some TVs also show a Network or ADB debugging toggle; turn it on too. Keep the TV switched on.

2. On your computer Open your assistant, paste the prompt from PROMPT.md, and fill in your TV model.

3. Follow along Accept the "Allow USB debugging?" prompt when it appears on the TV, then answer the checklist questions: which streaming apps you use, which four go in the dock, whether to keep the voice assistant, Chromecast and firmware updates.

That's it. The assistant backs up, debloats, builds and installs the launcher, and checks every step with screenshots pulled from the TV. On a 1 GB Mi TV the whole thing took one afternoon the first time; with this repo as context, people report about fifteen minutes.

What you get

A home screen that is yours again:

And a TV that stops working against you: no sponsored rows, no "Discover" nags, no analytics phoning home, no apps you never asked for.

Supported TVs

Anything running Android TV or Google TV: Xiaomi and Redmi, TCL, Hisense, Sony, OnePlus, Realme, Nvidia Shield and most others.

Not supported: Samsung (Tizen), LG (webOS) and Amazon Fire TV. They run different systems or won't let a third-party launcher take over Home.

Lists that people have tested and contributed live in examples/:

TV OS
Xiaomi Mi TV 4A (MiTV-MOOQ1) Android TV 10
Xiaomi MiTV-AXSO0 Android TV 9
TCL 55" 4K Google TV, 2023 (G10) Google TV 12
SANYO ATV R2 Android TV 9
OnePlus TV (D00) Google TV 14

Your TV not here? The prompt works regardless, it discovers the bloat itself. If you add your list afterwards, the next person with your model skips that step. See Contributing.

Doing it by hand

Everything the assistant does, you can run yourself. The tools need Python 3 and nothing else.

python3 -m venv tools/venv && tools/venv/bin/pip install -r tools/requirements.txt
export TV_HOST=192.168.1.50                                   # your TV's IP address

tools/venv/bin/python -I tools/tv.py --probe                 # model, Android version, firmware
tools/venv/bin/python -I tools/tv.py 'pm list packages'      # run one shell command on the TV
printf 'cmd1\ncmd2\n' | tools/venv/bin/python -I tools/tv.py --batch   # several, one connection

tools/disable.sh examples/xiaomi-mi-tv-4a/debloat.txt        # apply a debloat list
tools/restore.sh examples/xiaomi-mi-tv-4a/debloat.txt        # undo it and restore the stock launcher
Tool What it does
tools/tv.py A pure-Python ADB client: shell, batch, push, pull. Works where the stock adb binary is blocked.
tools/b64push.py Uploads larger files such as APKs as base64 chunks and verifies the checksum.
tools/disable.sh / tools/restore.sh Apply or undo a debloat list. PowerShell versions sit next to them.

Windows

The PowerShell scripts work without WSL or Git Bash. With Android Studio installed nothing else is needed: the install script uses Android Studio's bundled JDK and the default SDK location.

python -m venv tools\venv; tools\venv\Scripts\python.exe -m pip install -r tools\requirements.txt
powershell -ExecutionPolicy Bypass -File launcher\build-and-install.ps1 -TvHost 192.168.1.50
powershell -ExecutionPolicy Bypass -File tools\disable.ps1 -TvHost 192.168.1.50 examples\xiaomi-mi-tv-4a\debloat.txt
powershell -ExecutionPolicy Bypass -File tools\restore.ps1 -TvHost 192.168.1.50 examples\xiaomi-mi-tv-4a\debloat.txt

The install script stops before touching the stock launcher if the install or the home-screen switch fails. Git Bash also works; the .sh scripts detect a Windows venv and disable MSYS path rewriting themselves.

The launcher

A small native Android TV app (com.gathin.tvhome, about 1.6 MB), written in plain Java with AndroidX RecyclerView and nothing heavier. It is built for sets with 1 GB of RAM: no blur, no video, no network, no background services.

Configure it in launcher/app/src/main/res/values/config.xml: the dock order, apps to hide, your TV's Live TV package, and the number of columns.

Build and install with one command:

TV_HOST=192.168.1.50 launcher/build-and-install.sh

It needs JDK 17 and the Android SDK (platform 34, build-tools 34.0.0). On macOS:

brew install openjdk@17 android-commandlinetools
sdkmanager "platforms;android-34" "build-tools;34.0.0"

Without Homebrew, the script also finds a JDK 17 known to /usr/libexec/java_home and an SDK in ~/Library/Android/sdk, Android Studio's default. A release build (./gradlew assembleRelease) is smaller and faster on 1 GB sets; sign it yourself before installing.

Navigation is deliberate: Up and Down move exactly one row, Up from the dock goes to the top buttons, the ends of the button row don't fall through to tiles, and the last focused app is remembered when you come back, even after the app list changes.

Optional: the Clock screensaver

A large thin clock and the date over an ambient glow, in the launcher's style. Every minute the clock drifts to a new spot and the glow shifts colour. The system runs it only while the TV is idle. Turn it on over ADB, or pick "Clock" in the TV's screensaver settings:

tools/venv/bin/python -I tools/tv.py 'settings put secure screensaver_components com.gathin.tvhome/.ClockDream; settings put secure screensaver_enabled 1'

It starts after the TV's "screen off" idle time (settings get system screen_off_timeout).

Troubleshooting

Things that bit us or contributors, so they don't bite you.

Connecting

Working on the TV

Questions people ask

Is this safe? Can it brick the TV? No. Nothing is flashed, rooted or deleted. Packages are disabled for the user profile, which lives in the data partition, not in the system image. The firmware is untouched. If something goes wrong, tools/restore.sh puts everything back, and even without the tools you can re-enable apps from the TV's own settings.

What about firmware updates? Most lists disable the manufacturer's update service, so updates only arrive when you re-enable it on purpose. If an update does land, the worst case is that a package comes back enabled and you re-run the script.

Won't the apps break as their APIs change? The streaming apps still update through the Play Store, which is left alone. The launcher doesn't talk to them; it lists what's installed and launches it, using Android launcher intents that have been stable for over a decade.

How did it get access? Isn't that a security hole? Through the Android Debug Bridge, with one explicit "allow this computer" tap on the TV, the same as developing an Android app. The TV only trusts the key you approved. You can switch USB debugging off again afterwards and the launcher keeps working.

Can I just download the launcher APK? Build it yourself with the one-line script above; it takes about a minute and you control what goes on your TV. We don't publish prebuilt binaries.

Contributing

The most useful contribution is your TV's debloat list, so the next person with that model doesn't have to rediscover it. Launcher improvements and sharper prompt wording are welcome too. See CONTRIBUTING.md for the format and the testing we ask for.

Licence

MIT, see LICENSE. The Outfit typeface is under the SIL Open Font License, see launcher/FONT-LICENSE-OFL.txt.

tv-vibehack (Gathin23/tv-vibehack)

Searching Database…

1.9K ·GitHub
Tv-vibehack
What is this?A toolkit that strips bloatware and ads from any Android TV or Google TV over Wi-Fi (via ADB) and replaces the stock home screen with a clean, Apple TV-style launcher.
Is this an app I install, or a set of scripts and tools?It's both: a set of Python/shell/PowerShell scripts that debloat the TV over ADB, plus a small native Java Android TV launcher app you build and install yourself.
How do I actually run this on my TV?Enable USB debugging on the TV (Settings → About → tap Build 7 times → Developer options), then open a coding assistant like Claude Code, paste the prompt from PROMPT.md, fill in your TV model, and follow the on-screen checklist as it backs up, debloats, builds and installs the launcher.
Do I need Claude Code specifically, or any other tools?You need a computer on the same Wi-Fi as the TV and any coding assistant with shell access (Claude Code or similar); the Python ADB tools only need Python 3, and building the launcher needs JDK 17 and Android SDK platform 34.
Does this work on any TV brand?Only Android TV / Google TV devices (Xiaomi, TCL, Hisense, Sony, OnePlus, Realme, Nvidia Shield, etc.) are supported; Samsung Tizen, LG webOS and Amazon Fire TV run different systems and can't be debloated or re-launchered this way.
Do I need root access on the TV?No root is needed; everything runs through the standard Android Debug Bridge after you approve one 'allow this computer' prompt on the TV.
Can I run the setup from Windows or only macOS/Linux?Yes, there are PowerShell scripts for Windows (working without WSL or Git Bash) alongside the .sh scripts for macOS/Linux, and the install script auto-detects Android Studio's bundled JDK and SDK.
Does the launcher need an internet connection to work?The launcher itself does no networking — it has no blur, video, or background services, and simply lists and launches apps already installed on the TV.
Is it safe, and can it brick the TV?No — nothing is flashed, rooted or deleted; apps are only disabled per-user via pm disable-user, firmware stays untouched, and a restore script (or the TV's own settings) can re-enable everything.
Can I get a prebuilt launcher APK instead of building it?No, the project doesn't publish prebuilt binaries; you build the launcher yourself with a one-line gradle command, which takes about a minute.
Will the streaming apps break after switching launchers?No, streaming apps keep updating through the Play Store as normal; the launcher just lists installed apps and launches them via stable Android intents, without talking to the apps directly.
What does the new launcher actually look like?A pitch-black home screen with a four-app dock, a top shelf showing the focused app's name with an ambient color glow from its artwork, a sliding app grid, frosted Inputs/Wi-Fi/Settings buttons, and an optional drifting Clock screensaver.
What happens to firmware updates after debloating?Most debloat lists disable the manufacturer's update service, so updates only arrive if you manually re-enable it; if one does land and re-enables a package, you just re-run the debloat script.
What are similar projects?Shizuku-Next, tiny11builder, DSHA, winutil, Windows10Debloater, RemoveWindowsAI, universal-android-debloater, Winhance
Which topics is it in?xiaomi, debloat, adb, android-tv, launcher, script, powershell, android-app, shell, customization, utility, java
Creator
Gathin23
Size
4.8 MB
Stars
1.9K
Updated
CommitOct 18
Age
2d
Commits · 90 Days