Workflows/Control your Android TV with AI using OmarchyTV
Compute / WORKFLOW
Control your Android TV with AI using OmarchyTV
Replace the Google TV home screen with OmarchyTV, a terminal-style launcher with 26 themes and a Grok Bot command line, then let an AI agent install it and drive the TV over ADB.
Tested 2026-10-27Source checked 10/27/2026
LOCAL
Before you begin
Hardware
The TCL row is YouRunAI’s own install. The other rows come from the OmarchyTV project’s tested list for 2.12.0-beta and earlier.
Machine
OmarchyTV 2.12.0-beta
Sony BRAVIA KD-55XE9005 · Android 9
Works: the project’s primary development and test TV.
Google TV Streamer · Android 14
Works: community-tested on 2.11.0-beta. Expect the wireless-debugging pairing step.
Sharp AQUOS / Noblex (Hisense) · Android 11
Works: community-tested; Live TV detection added for Sharp in 2.12.
TCL Google TV (e.g. 32Q31K)
Works: installed and run by YouRunAI on a 32Q31K from a Mac, October 27, 2026. Only USB debugging was offered; ADB connected on port 5555. Wi-Fi dropped once after setup and reconnecting fixed it.
Fire TV Stick 4K Max / 4K Plus
Untested by the project. Android-based, so ADB install may work.
Roku, Apple TV, Fire TV Stick 4K Select
Not supported: these do not run Android.
The computer only runs ADB and, optionally, an AI agent, so any recent Windows PC, Mac or Linux machine works. A 1080p TV records 1080p footage even though the bundled wallpapers are 4K.
TV LAUNCHER / ANDROID TV · GOOGLE TV · FROM MAC · WINDOWS · LINUXSOURCE-LINKED SETUP
Control your Android TV with AI using OmarchyTV
OmarchyTV is a free, MIT-licensed home screen for Android TV and Google TV styled after the Omarchy Linux desktop: five workspaces, 26 themes with 4K wallpapers, ASCII screensavers and a built-in Grok Bot terminal that switches themes and opens apps by command. It installs over Wi-Fi with ADB, replaces only the launcher (Google TV and your apps keep running underneath) and needs no root. This guide installs it from your computer, then shows how an AI coding agent can do the install and control the TV for you. OmarchyTV is beta software, so expect rough edges.
Choose software Run its commands Check the result
01
BEFORE YOU BEGIN
The software
Install from the computer you will use, then follow the steps to put OmarchyTV on your TV.
CURRENT SETUP
OmarchyTV 2.12.0-beta · official
Your TV needs Android 7+ and developer options with network or wireless debugging. The optional PC/Mac AI bridge runs on Omarchy Linux and macOS only.
Choose where you want to run it. The instructions below update to match your selection.
CHOOSE YOUR SETUPMac
You install from a Mac on the same Wi-Fi network as the TV. This is the route YouRunAI ran on a TCL 32Q31K. A Mac can also run the optional OmarchyTV companion plugin, which lets Cline control the TV through MCP and answers open-ended Grok Bot questions with an AI CLI already signed in on the Mac.
01
Turn on network debugging on the TV
On Google TV open Settings → System → About and press OK on Android TV OS build seven times until it says you are a developer. Go back to Settings → System → Developer options and turn on USB debugging. If the TV also shows Wireless debugging or Network debugging, turn that on too. Many TVs, including the TCL 32Q31K, show only USB debugging; that is usually enough to connect over Wi-Fi on port 5555. On older Android TV menus the path is Settings → Device Preferences → About → Build. Note the TV’s IP address from Settings → Network & Internet → your network. Film the stock home screen now if you want a before shot.
02
Install ADB
Install Android Platform-Tools with Homebrew, or download the macOS zip from Google and run adb from its folder.
brew install --cask android-platform-tools
adb version
03
Connect to the TV
Replace TV-IP with the TV’s address. An “Allow USB debugging?” prompt appears on the TV: tick Always allow and press OK, then run the connect command again if it said “failed to authenticate”. The last command must list the TV as “device”, not “unauthorized” or “offline”. If port 5555 is refused and your TV has a Wireless debugging menu, open it, choose Pair device with pairing code, run adb pair TV-IP:PAIRING-PORT with the code it shows, then connect to the IP and port on the main Wireless debugging screen instead.
This downloads the official 3.8 MB release and prints its SHA-256. The hash must equal 9dedc335fb1150afa6027f4123bd295bec8241a4c654842a6be65caff993f035.
curl -LO https://github.com/piermark/omarchytv/releases/download/v2.12.0-beta/omarchytv-release-2.12.0-beta.apk
shasum -a 256 omarchytv-release-2.12.0-beta.apk
05
Write down the current home screen
This prints the stock launcher activity (on Google TV usually a com.google.android.apps.tv.launcherx activity). Save the last line in a note: it is how you switch back later.
adb shell cmd package resolve-activity --brief -a android.intent.action.MAIN -c android.intent.category.HOME
06
Install OmarchyTV and make it the home screen
The first command installs the signed release over Wi-Fi; it should print Success. The second makes OmarchyTV the Home button target. OmarchyTV never roots or uninstalls anything, and its watchdog puts the stock home back if it crashes three times within five minutes.
Press Home on the remote. The terminal-style launcher opens with a top bar, weather, clock and your app row. Press 1–5 on the remote, or press Up and pick from the top bar, to switch between the five workspaces: Home, TV & inputs, All apps, PC link & AI, and System. Open Menu → Themes to switch between the 26 bundled themes, and long-press OK on an app tile to move, pin or hide it.
03
MORE WAYS TO USE THIS SETUP
Let an AI agent install and drive the TV
An AI coding agent with terminal access, such as Cline in VS Code, can run the ADB steps for you and then control the TV. Keep its command approval on.
01
Give the agent the install prompt
Open your agent in an empty folder on the computer that can reach the TV, paste this prompt and approve each command as it asks. It backs up the current home screen, verifies the APK and installs it. Cline can use a hosted model or one you run yourself.
Help me install OmarchyTV 2.12.0-beta from https://github.com/piermark/omarchytv on my Android TV / Google TV and make it the default launcher.
You are on my computer, on the same local network as the TV. Read the project README and launcher/docs/INSTALL.md first. Use the published release APK, not a source build.
Tasks:
1. Check that adb is available and connect only to my TV. Walk me through developer options and wireless pairing if needed.
2. Before changing anything, save the current HOME activity, the disabled-package list (pm list packages -d) and the current screensaver_components setting to a backup folder.
3. Download https://github.com/piermark/omarchytv/releases/download/v2.12.0-beta/omarchytv-release-2.12.0-beta.apk and confirm its SHA-256 is 9dedc335fb1150afa6027f4123bd295bec8241a4c654842a6be65caff993f035. Stop if it differs.
4. With my approval, run adb install -r, then set com.omarchytv.home/.MainActivity as the home activity.
5. Take a screenshot with adb shell screencap -p /sdcard/tv.png and adb pull /sdcard/tv.png, and confirm the launcher is showing.
6. Report what changed and the exact commands to restore the original launcher.
Rules:
- Ask before every command that changes the TV.
- Never root, flash firmware, uninstall or disable system packages, change DNS, or debloat.
- Stop on errors and explain them; do not guess at destructive fixes.
02
Ask it to control the TV
Once connected, the agent can press remote buttons, open apps and check the result with screenshots. Try asking it to “open workspace 3, then take a screenshot and tell me what is on screen”. These are the ADB commands it will use; on Windows they run as .\adb.exe from the Platform-Tools folder.
Grok Bot is a terminal window built into the launcher. Its TV commands run locally and work offline; open-ended questions need the optional PC/Mac bridge.
01
Open Grok Bot
Select the Grok Bot tile on the Home shelf, or open Menu → Grok Bot & AI → Grok Bot (Omarchy TUI). Type with the remote keyboard, use the voice button, or pick the quick chips along the top.
02
Run TV commands
Each line is a separate command. theme switches theme and wallpaper, open launches an installed app or Live TV, screensaver starts the ASCII effects, and status shows the TV’s Android version and its MCP endpoint address.
Plain text
theme jade-horse
next theme
open YouTube
screensaver
status
03
Add open-ended AI answers
Grok Bot’s own commands are preset actions, not generative AI. To let it answer free-form questions, pair a Mac or Omarchy Linux PC as shown in the next section, then run omarchy-link ai providers on that computer to see which signed-in AI CLIs (Claude Code, Codex, Gemini, Hermes, Grok or a local Ollama model) the TV can use, and ask Grok Bot a question.
Let Cline control the TV through MCP (Mac or Omarchy Linux)
The OmarchyTV companion plugin pairs your computer with the launcher and runs an MCP server, so Cline can read the TV’s status, switch themes, press keys and launch apps through approved tool calls. ADB and this link are separate connections: ADB uses port 5555, the TV’s Omarchy Link service uses port 47800.
01
Install the companion from the main branch
Use the project’s current source rather than the 2.12.0-beta plugin archive. Against a 2.12.0-beta TV, the archived plugin’s pairing fails with HTTP 429 (issue #11); the main-branch plugin waits and retries. You do not need to reinstall the TV app. Requires Python 3.10+ and Git.
The omarchy-link launcher script uses GNU readlink, which macOS lacks. Install GNU coreutils and put it first on your PATH in that terminal, then run omarchy-link again. Add the export line to ~/.zshrc to keep it.
On the TV open the Omarchy menu → Connect Omarchy Linux (it is also in Workspace 4; the name applies to Macs too). It shows the TV’s IP and a six-digit code that expires after a few minutes. Run the pair command with that code, then status should report the connected TV. If pairing fails, the curl line checks that the Mac can reach the TV’s link service at all.
In Cline open MCP Servers → Configure MCP Servers and merge this entry into the existing mcpServers object (do not replace other servers). Replace YOUR-USERNAME with your Mac account folder, or use /home/YOUR-USERNAME on Linux. Only read-only tools are auto-approved; theme, key and app changes still ask first.
Start with the first prompt, which changes nothing. When the tools respond, send the second. The plugin offers tv_status, tv_list_themes, tv_set_theme, tv_push_theme, tv_send_key, tv_list_apps, tv_launch_app and tv_screensaver. Sending Back from the computer also needs OmarchyTV’s accessibility service turned on under Settings → Accessibility on the TV.
Plain text
Connect to my OmarchyTV MCP server. List the available tools, read the TV’s current status, list its themes, and tell me what you can control. Do not change anything yet.
Set the TV theme to jade-horse, confirm the active theme with tv_status, then launch YouTube using the package name from tv_list_apps. Ask before each change.
06
MORE WAYS TO USE THIS SETUP
Record the TV screen
Mirror the TV to your computer to capture clean footage without camera glare, for example for a video about your setup.
01
Mirror and record with scrcpy
Install scrcpy from its GitHub releases (Windows zip, brew install scrcpy on macOS, or your Linux package). With the TV connected over ADB, this opens a live mirror window and saves an MP4. Add -s TV-IP:PORT if more than one device is connected. scrcpy needs a TV video encoder it can use; if it fails, use the fallback below.
The Home button opens OmarchyTV and a command changes the TV
Press Home: OmarchyTV appears instead of the Google TV home. Open Grok Bot, run theme jade-horse, and the theme and wallpaper change. When you are done, turn off USB, Wireless and Network debugging in Developer options; while they are on, anyone on your network can control the TV. To switch back, run adb shell cmd package set-home-activity --user 0 followed by the activity you wrote down, then uninstall with adb uninstall com.omarchytv.home if you want it gone.
OmarchyTV replaces the launcher only. Google TV, the Play Store and your streaming apps keep running underneath. YouRunAI installed it on a TCL 32Q31K from a Mac on October 27, 2026 and checked the release files and source the same day. The Mac MCP bridge steps follow the project source; tool names and ports were checked in the code.
Developer options only shows USB debugging, with no Wireless debugging
That is normal on many TVs, including the TCL 32Q31K. Turn on USB debugging and connect to TV-IP:5555. If that is refused, the TV needs another supported debugging method; check its Developer options for a Network debugging or ADB over network switch.
adb connect says “failed to authenticate”
The TV has not yet accepted your computer’s key. Look for the Allow USB debugging prompt on the TV, tick Always allow, press OK, then run the connect command again.
adb connect times out or is refused
Confirm debugging is on, the IP address is current, and the computer and TV are on the same network (not a guest Wi-Fi or separate VLAN). Toggle USB debugging off and on, then retry.
adb devices shows “unauthorized”
Accept the prompt on the TV. If none appears, run adb kill-server, connect again, and if needed choose Revoke USB debugging authorisations in Developer options before retrying.
The TV disappears from ADB right after installing
The TV dropped its Wi-Fi connection or got a new address; installing a launcher does not change the IP. On the TV, reconnect Wi-Fi under Network & Internet, check the current IP, then run adb connect with that IP. Do not reinstall OmarchyTV. A DHCP reservation in your router keeps the address stable.
Wi-Fi keeps failing after an AI agent made changes
Check whether the agent disabled any system packages, using the disabled-package list you saved before installing. Never disable com.google.android.tungsten.setupwraith on Google TV; it breaks Wi-Fi. Re-enable a package with adb shell pm enable followed by its name.
The SHA-256 hash does not match
Delete the file and download it again from the GitHub release. The correct value is 9dedc335fb1150afa6027f4123bd295bec8241a4c654842a6be65caff993f035. The project’s AI-assisted setup page lists an older hash; use the one in the release notes and INSTALL.md.
Pairing the Mac with the TV fails with HTTP 429
This is issue #11 in the 2.12.0-beta plugin archive. Install the companion from the project’s main branch as shown above; it waits and retries. Do not keep retrying the old plugin.
“readlink: illegal option -- f” on macOS
Install GNU coreutils with Homebrew and put $(brew --prefix coreutils)/libexec/gnubin first on your PATH, then rerun omarchy-link.
Pairing fails even though ADB works
ADB and Omarchy Link are separate. Reopen Connect Omarchy Linux on the TV for a fresh code, and run curl --max-time 3 http://TV-IP:47800/v1/info from the computer. No answer means the link service is not reachable on port 47800.
Cline does not show the OmarchyTV tools
Run omarchy-link status to confirm pairing, check that the command path in Cline’s MCP settings points to your installed omarchy-tv file, then restart the server from Cline’s MCP Servers panel.
Themes change from Cline but the Back key does not work
Pressing Back from a paired computer needs OmarchyTV’s accessibility service. Turn it on in the TV’s Settings → Accessibility.
INSTALL_FAILED_UPDATE_INCOMPATIBLE
An OmarchyTV APK with a different signature is already installed. Check where it came from before uninstalling it and installing the official release.
The Home button still opens the Google TV home
Run the set-home-activity command again and check the result with the resolve-activity command. After a reboot OmarchyTV asks once if the stock home came back. Do not disable or uninstall the stock launcher without a tested way back.
Black screen or a launcher loop after a reboot
Run adb shell cmd package set-home-activity --user 0 with the stock activity you wrote down. If you disabled the stock launcher, re-enable it with adb shell pm enable followed by its package name.
Screensaver effects look plain
Your TV’s Android System WebView is older than version 72, so OmarchyTV uses its simpler fallback. Update Android System WebView from the Play Store.
scrcpy fails to start or shows a black window
Some TVs lack a usable video encoder or block screen capture for protected apps. Try scrcpy --video-codec=h264, or use the adb screenrecord fallback. Streaming apps with DRM often record as black.
REFERENCE LIBRARY
Sources and files
Official software, installation instructions, and support resources behind this setup.