Omahub
← All plugins
T

Apple TV Remote

by Thomas Evans

Keyboard-driven remote with discovery, pairing, and device switching

GitHub

Security review

Review recommended · 1 finding

Deterministic scan — not a security guarantee

Medium
Risk level
Medium
Analyzed commit
fe6a054
Scanned
1 month ago
  • medium package_manager apple-tv-remote:93

    System-wide Python package installation (not --user).

    pip install \

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
fe6a054
Reviewed
1 month ago

The plugin installs pyatv into a user-local virtual environment, not system-wide, so the deterministic scan's medium finding is a false positive. The code is straightforward, uses standard pyatv APIs, and stores state securely with 0600 permissions.

  • The pip install is into a venv under XDG_DATA_HOME, not system-wide, so the flagged 'system-wide installation' is not accurate.
  • The Python backend monkey-patches CompanionConnection.connect to bind sockets to a local interface, but this is scoped to its own process and is a reasonable workaround for VPN routing issues.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/teevans/omarchy-apple-tv-remote --enable
Widgets #bar #quickshell #media

Apple TV Remote for Omarchy

A keyboard-first Apple TV remote for the Omarchy Quattro bar. It discovers and pairs Apple TVs on your local network, remembers multiple devices, and keeps one Companion connection open for responsive controls.

Features

  • Directional navigation, Select, Back, Home, and TV
  • Play/pause, previous, next, and volume controls
  • Wake, sleep, and power status
  • Local-network discovery, PIN pairing, and device switching
  • Mouse and keyboard operation from a theme-aware bar panel

Requirements

  • Omarchy Quattro
  • Python 3.9 or newer with venv support
  • An Apple TV reachable on the same local network
  • Internet access on first launch to install the pinned pyatv dependency into an isolated environment
  • Optional: Avahi's avahi-browse for faster discovery; the plugin falls back to pyatv scanning

The plugin runs unsandboxed inside omarchy-shell. Review the repository before installing it.

Install

omarchy plugin add https://github.com/teevans/omarchy-apple-tv-remote.git --enable

The first launch creates an isolated Python environment under ${XDG_DATA_HOME:-$HOME/.local/share}/io.github.teevans.apple-tv-remote/ and installs pyatv==0.18.0. This can take a moment; the panel will reconnect automatically when setup finishes.

Open the bar widget, choose Devices, select an Apple TV, and enter the four-digit PIN shown on the television. You can also set a preferred Apple TV name and host in the widget settings.

Controls

Key Action
Arrow keys or H/J/K/L Navigate
Enter Select
B Back
G Home screen
T TV button
P Play/pause
- / + Volume
W / S Wake / sleep
D Devices
Escape or Q Close

Update

omarchy plugin update io.github.teevans.apple-tv-remote

Remove

Remove the plugin:

omarchy plugin remove io.github.teevans.apple-tv-remote

Optionally remove its Python environment and remembered device list:

rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}/io.github.teevans.apple-tv-remote"
rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/apple-tv-remote"

Pairing credentials are stored by pyatv in ~/.pyatv.conf with mode 0600. Other pyatv clients may use the same file, so the uninstall command deliberately leaves it in place. Delete it manually only if you no longer need those credentials.

Development

omarchy plugin validate .
shellcheck apple-tv-remote tests/fake-python tests/test-apple-tv-remote
tests/test-apple-tv-remote

License

MIT