Seagey/couch-tv

What it does

couch-tv replaces the stock Google TV home screen with an ad-free Android TV launcher: rotating scene backgrounds with a large glass clock, weather, your apps in your own order, and a Keep watching row. It also ships a phone web remote and a small Python bridge that talks to the TV over the Android TV Remote protocol and ADB, enabling remote control, turn-on, show search, and an optional Claude assistant ("put on that show about the lawyer who never went to law school"). Samsung Tizen and LG webOS paths exist as separately installed apps that need an always-on bridge computer; the LG path is built from documentation and has not yet run on a real LG TV.

On Android TV and Google TV, replacing the home gives the full feature set. Fire TV (Fire OS) supports the on-TV app variant, which watches for Amazon's home and puts couch-tv back on top, but Amazon's home still flashes up first. Roku, Apple TV, VIDAA-based Hisense and newer Fire TV sticks on Vega OS are unsupported.

Quick start

You need a Google TV or Android TV set (Android 9 or newer), a Mac or Linux computer on the same Wi-Fi with Python 3.11+, and the couch-tv-home.apk from the Releases page. The README suggests handing the repo to a coding agent and saying "set this up on my TV": it reads AGENTS.md and asks which TV and which of the three options you want.

Without an agent:

1. On the TV, enable Developer options and USB debugging, and note the TV's IP address.
2. Clone and prepare the environment:

git clone https://github.com/Seagey/couch-tv.git
cd couch-tv
python3 --version
python3 -m venv .venv
.venv/bin/pip install -r bridge/requirements.txt
cp config.example.json config.json

3. Optionally check what your TV supports, which changes nothing on it:

.venv/bin/python scripts/find-tvs.py
.venv/bin/python scripts/check-tv.py <tv address>

4. Fill in tvs, people, weather and country in config.json.
5. Option A (home only, no computer stays on): install the home screen with the TV address and downloaded APK:

TV_IP=<your tv address> APK=couch-tv-home.apk sh tv-home/tools/apply.sh

Option B additionally pairs the bridge, builds the phone remote with Node 20+, runs bridge/server.py, and passes BRIDGE_URL=http://<computer>:5400 to apply.sh. The full step-by-step sequence is in the README setup section.

Before running apply.sh, read the undo guide: it switches off the Google TV home and setup wizard, and on some TVs switching off the wizard makes the TV forget its Wi-Fi. KEEP_SETUP=1 avoids that risk at the cost of the wizard possibly still winning the Home button.

Constraints

The TV must be Android 9+ with Developer options on. Replacing the Google home on Google TV can break some Google Home features and the remote's YouTube button, and a Google TV update can restore the Google home; with Option B the bridge re-disables it daily, with Option A you rerun apply.sh. The bridge only works on your home network, has no password, so anyone on your Wi-Fi can use the remote and the Claude assistant; keeping it off the internet and using a guest network for visitors is the documented mitigation. Claude search requires Claude Code installed and logged in, invokes claude -p, and strips ANTHROPIC_API_KEY so no API key is billed. Watch history and picks stay in bridge/data/ and are gitignored.

Samsung and LG need a computer that stays on and only offer an app that opens itself rather than a true home screen; no screenshots or "what is playing" on those platforms, so playback actions are timing-based. The bridge's own messages remain English in every UI language. The project is MIT licensed and offers no support promise beyond the TVs it was built on.

HotRepo's take

couch-tv appeared in HotRepo's new-project list for Python on 1 November 2026, reporting 48 stars gained across roughly a day-long window, with the repository at 177 stars and 26 forks by the end of that window. The hourly samples show the count climbing from 121 on 30 October to 177 by midday on 1 November, including a small dip from 132 to 129 on 31 October. With no entry on the all-language GitHub daily rank recorded, the observable signal is steady small-repo growth rather than a breakout. The README itself counts sixteen forks and six contributors whose work was merged, which is unusual for a repository this young and is the most concrete sign that the project is attracting builders rather than only stargazers.