tv-vibehack

Your TV, minus the ads. Debloat any Android TV / Google TV over ADB and give it a clean,
tvOS-inspired launcher. Hand the prompt to Claude Code or any coding assistant, answer a few
questions about which apps you use, and it does the rest on the real TV.

Stock home screen	After

Everything is reversible: packages are disabled, never uninstalled, and a restore script puts the
stock launcher back.

Quick start

1. On the TV: Settings → Device Preferences → About → press OK on Build seven times → back →
   Developer options → turn on USB debugging (and Network/ADB debugging if your TV shows it).
   Keep the TV on and on the same Wi-Fi as your computer.
2. Open Claude Code (or your assistant of choice) on your computer and paste the prompt from
   PROMPT.md, filling in your TV model.
3. Accept the "Allow USB debugging?" prompt on the TV when told to, then answer the checklist
   questions (which apps you use, which four go in the dock).

That's it. The assistant backs up, debloats, builds and installs the launcher, and verifies each
step with screenshots from the TV. If you'd rather do it by hand, the pieces are below.

What's in the repo

The launcher

A small native Android TV home screen (com.gathin.tvhome), built for sets with 1 GB of RAM:

• Pitch-black background, like Apple TV 4K.
• A dock at the bottom in a lighter rounded band with the four apps you choose. The shelf above
  shows the focused dock app's name in large type with an ambient glow sampled from its banner.
  Press Down and the dock slides up to reveal the rest of your apps in a grid.
• One translucent glass highlight springs from tile to tile. The focused tile lifts and shows its
  name.
• Frosted pills top right: Inputs (a dropdown of HDMI ports, AV and Live TV), Wi-Fi
  (shows the network name) and Settings. Greeting, a large thin clock and the date top left,
  set in Outfit.
• Deterministic D-pad navigation, last focused tile remembered, staggered entrance animation.
  No blur, no video, no network, no background services.

Configure it in launcher/app/src/main/res/values/config.xml:
dock order, hidden apps, Live TV package and columns. Build and install with

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

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".

Windows

PowerShell versions of the scripts sit next to the bash ones. With Android Studio installed, nothing
else is needed: the script uses Android Studio's bundled JDK and the default SDK location, and Gradle
downloads platform 34 and build-tools 34.0.0 on the first build if the SDK licence is accepted.

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

build-and-install.ps1 stops before touching the stock launcher if the install or setting the new
home screen fails.

Talking to the TV by hand

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
tools/venv/bin/python -I tools/tv.py --probe                 # model, Android version, firmware
tools/venv/bin/python -I tools/tv.py 'pm list packages'      # one command
printf 'cmd1\ncmd2\n' | tools/venv/bin/python -I tools/tv.py --batch
tools/disable.sh examples/xiaomi-mi-tv-4a/debloat.txt        # apply a list
tools/restore.sh examples/xiaomi-mi-tv-4a/debloat.txt        # undo it, restore stock launcher

Gotchas we hit

• Windows PowerShell 5.1 prepends a byte-order mark to text piped into a native program, which
  turned the first --batch command into pm ("inaccessible or not found"). tools/tv.py now
  reads stdin as utf-8-sig, and the .ps1 scripts pipe UTF-8 without a BOM.
• macOS: adb connect says "No route to host" while the port is clearly open. Recent macOS
  treats the Google-signed adb as its own app under Local Network privacy and silently blocks it.
  tools/tv.py avoids the binary entirely.
• No "wireless debugging" toggle on some TVs (Xiaomi among them). USB debugging alone opens
  network ADB on port 5555.
• Windows (Git Bash): the scripts pick up tools/venv/Scripts/python.exe and set
  MSYS_NO_PATHCONV=1, otherwise Git Bash rewrites device paths like /data/local/tmp into Windows
  paths. launcher/build-and-install.sh defaults to Homebrew paths, so set JAVA_HOME and
  ANDROID_HOME first.
• Chained pm commands (pm disable a; pm disable b) may silently stop after the first. Run
  one per shell call; --batch does this.
• Large pushes hang through the Python client. Use tools/b64push.py for APKs.
• Screenshots come out empty (0-byte PNG) while Live TV or an HDMI input is on screen (seen on
  TCL). Press Home before screencap.
• Disable the stock launcher only after the new one is installed, or the Home button lands on
  a factory test app.
• Third-party launchers often charge for basics like a custom wallpaper. Hence launcher/.
• No on-screen keyboard after switching launchers (seen on Xiaomi): the default input method
  pointed at a Baidu IME that isn't installed. Fix with
  tools/tv.py 'ime set com.google.android.inputmethod.latin/com.android.inputmethod.latin.LatinIME'.

Supported TVs

Anything running Android TV or Google TV: Xiaomi/Redmi, TCL, Hisense, Sony, OnePlus, Realme,
Nvidia Shield and most others. Not Samsung Tizen, LG webOS or Amazon Fire TV (different OS, no ADB
launcher replacement). Tested so far on the models in examples/.

Contributing

Add your TV's debloat list, improve the launcher, or sharpen the prompt. See
CONTRIBUTING.md.

Licence

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