couch-tv README

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

couch-tv on a TV: the Night home screen with the glass clock, Keep watching and the app dock

Your own home screen and phone remote for the TV.
Scenes with a glass clock, your apps in your order, Keep watching across apps, and a phone remote that finds a show and starts it. No ads on the home screen. Open source.

Latest release MIT licence Google TV, Android TV, Fire TV, Samsung, LG, Roku, Apple TV and more

Set it up  ·  Which TVs  ·  Docs  ·  What's new

Get started

  1. With your AI agent, the easiest way. Open this folder in Claude Code (or any coding agent) and say "set this up on my TV". It reads AGENTS.md, finds your TV, asks which option you want and a few questions (who watches, the look, your apps), reads the plan back, and changes nothing on the TV until you say yes.
  2. From your phone or a computer: couchtv.sites.underseage.studio, with the free Setup app on a Mac or Windows computer. It also checks whether your TV will work.
  3. By hand: docs/SETUP.md has every step, from developer mode to the TV home, and how to undo it.

Pick the way for your TV before you start. Not every way does the whole job on every TV:

Way What you need Google TV Android TV Fire TV Samsung or LG
AI agent (AGENTS.md) A computer on the TV's Wi-Fi with Claude Code or another coding agent Yes, Home button included Yes Yes, Home button included (Amazon's home flashes up first). The full phone remote keeps a computer on at home Yes, as an app that a computer at home that stays on opens. Their own Home button still opens their own menu
From your phone (website) The TV remote and a phone on the same Wi-Fi. No computer Only part: the app and the phone remote, but Google keeps the Home button. AI or the Setup app adds the Home button once, even afterwards Yes. On Android TV 10 and newer the app asks Android to make it the home Only part: Home needs three one off grants from a computer, and on current Fire OS the phone remote can't press keys or type No
Setup app (website) A Mac or Windows computer on the same Wi-Fi, once Yes, Home button included Yes, Android TV 7.1 and newer Yes on Fire OS 6, 7 and 8 (Amazon's home flashes up first) No
By hand (docs/SETUP.md) A Mac or Linux computer with Python 3.11 or newer Yes Yes on-tv/README.md, Fire TV docs/SAMSUNG.md, docs/LG.md, with a computer at home that stays on

Other TVs: Will it work on my TV?

[!NOTE] Set couch-tv up with 0.10 or older on a Google TV? 0.11 and newer leave the Google home and setup apps switched on. Read If your TV loops after a restart before you next restart your TV.

Updates

The newest release is 0.12 (9 November 2026), on the Releases page. These are on main, in the next release:

Every change, with credits: docs/UPDATES.md.

Three ways to run it

Will it work on my TV?

A is the TV home only, B adds the computer bridge, C lives on the TV (the three ways).

Your TV A B C
Google TV Yes Yes Partial
Google TV box Yes Yes Partial
Older Android TV Yes Yes Yes
Android 6 TV Experimental Not tested Experimental
XGIMI projector Yes Not reported Yes
Nvidia Shield Yes, untested Yes Yes, untested
Fire TV on Fire OS Partial Partial Partial
Fire TV on Vega OS App only Beta No
Samsung App only As an app No
LG App only As an app No
Roku App only As a channel No
Hisense VIDAA App only Beta No
Philips with Titan OS Not yet Remote only, Beta No
Older Philips with Saphi No Beta No
VIZIO No Remote, Beta (home in the TV's webview by hand, Beta, one set) No
Panasonic Viera No Beta No
Apple TV No Beta No
TiVo OS No Beta No

Beta means a computer at home that stays on, and the maker's own Home button still opens the maker's own home.

It depends on the model, not the brand. Open Settings, System, About (or Device Preferences, About) on the TV: "Android TV OS" means yes (brand by brand).

Want everything on a TV that is not Google TV or Android TV? Plug in a Google TV box (for example the Google TV Streamer) and set couch-tv up on that, and you get everything, on any TV with an HDMI port.

Test your own TV (changes nothing on it, and installs nothing outside this folder):

git clone https://github.com/Seagey/couch-tv.git && cd couch-tv
python3 --version                                  # needs 3.11 or newer
python3 -m venv .venv && .venv/bin/pip install -r bridge/requirements.txt
.venv/bin/python scripts/find-tvs.py               # lists the TVs on your Wi-Fi
.venv/bin/python scripts/check-tv.py <tv address>  # says which options that TV can run

It knocks on the ports each kind of TV answers on, so it can tell a Samsung from a Google TV without touching anything. More, including the check by hand and --adb: docs/PLATFORMS.md.

Home backgrounds

Five scenes take turns every 20 seconds, each with a big glass clock that sits just behind the scenery: the peaks, the volcano and the misty hills overlap the digits, and on the lake the clock floats with its reflection under the water. Or pick the Classic look, your own photos, or a scene you design yourself.

Night Golden hour Waterline Fog Dawn Classic

Night, Golden hour, Waterline, Fog, Dawn and Classic. Shown with sample shows and sample people.

The phone remote

Your phone becomes the remote: arrows, volume, typing and the power button. Ask for a show by name ("put on Bluey") and couch-tv finds where it streams and starts it in the right app, past "Who's watching?" on Android TV. There is an optional assistant for "put on something funny": Claude with the bridge, or Claude and other AI services in on-TV mode. Needs option B or C.

The phone remote: the Remote tab with The Bear playing, and the Watch tab with Keep watching and the apps

The phone remote · TV remotes and keys · Ask with any AI service

Kids mode

A kids profile's home is one shelf of shows you chose, as big posters that open straight into each show, plus only the apps you allow. No other apps, no settings, no grown ups' Keep watching. Leaving it needs the parent PIN. Optional, and off unless you set it up.

Kids mode on the TV The parent PIN

How Kids mode works and what it cannot do · Every setting

Settings on the TV

No computer and no config.json needed for the everyday settings. Pick the gear in the dock, or press the remote's own Settings button, and change the language, the place for the weather, the look and scenes, your apps and their order, the people and the quick buttons, with any remote.

Home settings on the TV

Every Home setting in full

And a lot more

One home, many TVs

The same home on Google TV and Android TV, an app on Apple TV, a channel on Roku, and Fire TV, Samsung and LG versions, with Beta paths for more.

Couch TV on Apple TV The couch-tv channel on Roku couch-tv on a Fire TV Stick

Apple TV (Beta), Roku and a Fire TV Stick.

Documentation

Set up Use Your TV
Every setup step The TV home Samsung
config.json, every setting The phone remote LG
On-TV mode, no computer TV remotes and keys Roku
The bridge in Docker Make your own scene Fire TV Stick
For your AI agent Ask with any AI service Hisense VIDAA
Take couch-tv off All updates Apple TV
Troubleshooting Two TVs in sync Every brand
Which TVs work How it works, privacy, limits Philips, Panasonic, VIZIO and more

Everything else: docs/.

Credits

Shout me a coffee

couch-tv is free. If it made your day a bit easier and you'd like to say thanks, you can shout me a coffee, any amount you like.

MIT licence, see LICENSE. Your settings, secrets and watch history stay on your own computer and TV: privacy and safety.

couch-tv (Seagey/couch-tv)

google-tv
Searching Database…

What is this?couch-tv replaces the ad-filled home screen on a Google TV (and now Samsung TV) with your own ad-free one, adds a phone remote, and can add an optional Claude assistant that understands requests like finding a show by description.
Is this something I install myself, or does my AI agent set it up for me?You hand the repo to your AI coding agent, which detects whether you have a Google TV or a Samsung TV and walks you through the matching setup path instead of you following manual install steps.
How do I get it running on my TV?There are three options: A) replace just the home screen, no computer needed; B) add a computer bridge for the phone remote, search, and the Claude assistant; or C) run everything inside an app on the TV itself with no computer.
Do I need a computer running all the time?Only if you want the phone remote, 'put on Bluey' search, or the Claude assistant (option B) — that needs a Mac, Linux box, or Raspberry Pi staying on at home; the home-screen-only and on-TV options don't need one.
Does it work the same way on every TV brand?No — it's a true home screen replacement only on Google TV/Android TV; on Samsung it's just an app you open yourself since Samsung won't let anything replace its real home, and the newest Fire TV sticks (Vega OS) aren't supported at all.
Can the Claude assistant see what's actually playing on a Samsung TV?No — Samsung doesn't expose screenshots or playback state to the network, so couch-tv times its button presses instead of reading the screen, and on profile-selection screens it just picks whichever profile is highlighted.
What do the animated home screen backgrounds look like?Five scenes (peaks, volcano, misty hills, waterline, fog) take turns every 20 seconds behind a translucent glass clock, and you can add your own photos or design a custom scene with its own clock overlay.
Can it integrate with my smart home setup?Yes, optionally — if you already run Home Assistant it can show per-room air conditioning, your scenes and scripts as tiles, and a doorbell camera overlay, but it stays off until you configure it yourself.
Will couch-tv nag me with update notifications?Only if you opt in: the first launch asks once whether to check for new versions, and even then it only checks GitHub about once a week, with a manual 'Check for updates now' option always available.
Can I use it on a Fire TV stick?Yes, with caveats — on Fire OS it works via workarounds, taking the Home key back after Amazon's own launcher briefly flashes up, but it isn't supported at all on the newer Fire TV Vega OS.
Creator
Seagey
Size
33.8 MB
Stars
1.5K
Age
23d
Commits · 90 Days