Buoy for React Native TV — devtools for Apple TV & Android TV apps

TV is React Native — the same packages, the same install. What changes is the surface. A TV has no touch, so Buoy mounts headless and renders nothing on the screen, and Buoy Desktop becomes the whole interface.

TV support is in beta. The documented target set includes Apple TV simulators and Android TV emulators. Check Known limits and test your app on its actual target hardware; these pages are not a test record for every device and build.

Two ways to reach your running TV app:

On your desktop — Buoy Desktop, a free dashboard for macOS, Windows & Linux. Your TV device appears in the same switcher as your phones, with the same panels.
Through your AI — the MCP server lets Claude Code, Cursor, or any MCP editor inspect your live TV app (Pro).

There is no third way on TV: the in-app floating menu is deliberately absent.

Start here

Let your coding agent install Buoy in your app:

Let your coding agent install itClaude Code · Cursor · Codex

Read the prompt before you paste it

Install Buoy, the in-app devtools, in this React Native TV project. Read the full instructions first: curl -fsSL https://buoy.gg/install-tv.md Read the raw text, not a summary. If curl is unavailable, use any HTTP tool you have. Ask me to paste the document only if nothing can fetch it. Do the install yourself: inspect the repo, run the commands, edit the files. Do not hand me steps you can run. Work out the routine decisions from the repo: package manager, which app to target, Expo TV or bare, where the headless mount goes, which Buoy tools match the dependencies already installed. If Buoy is already partly installed, repair and extend it; never add a second mount, provider, or package set. When instructions conflict, follow this order: what I say here, then the document's rules about which packages exist and what needs my permission, then this project's own constraints, then the rest of the document, then your judgment. Ask me before: adding a native dependency, opening a browser or creating an account, changing what a release build does beyond what the document specifies, or anything hard to undo. Do not commit. You are not done when the package installs. Run this project's existing typecheck; add no tooling. Then report what you installed and why, what you skipped and why, every file you changed, what you verified, and the exact steps I take with Buoy Desktop to confirm the TV connects and captures a request.

The prompt asks your agent to inspect the project, choose matching tools and guide setup. Review its edits and verify the connection on your device.Read the setup instructions

To install by hand, follow the Quick Start.

TV uses D-pad navigation. A focusable debug overlay can enter that focus order and affect the behavior under test. Mount Buoy headless to keep its controls on Desktop and leave the app screen available for inspection.

The two TV tools

These exist because of TV. Both are desktop surfaces — the packages you install only capture.

Tool	Package	What it does
TV Remote	`@buoy-gg/tv-remote`	Press the D-pad, Select, Menu, holds, media keys and typed text from Buoy Desktop; record a macro and replay it with per-step confirmation.
Focus Inspector	`@buoy-gg/focus-inspector`	Every focus move with its direction, the full focusable inventory, and flags for focus that gets stuck, vanishes, or is never reached.

Use the remote event history and focus transitions together to record the sequence leading to a focus problem.

Presses come from your Mac, not from inside the app

Buoy Desktop injects with adb shell input keyevent on Android TV and idb ui key on the Apple TV simulator. Both travel the platform's real input pipeline, so focus moves through the same engine a physical remote drives. The installed package only observes — it reports which events your app actually received, which is what tells "the app handled that press" apart from "something swallowed it."

The app package observes input events; host tools inject supported presses. A JavaScript handler call alone does not reproduce the platform focus-navigation path.

What works where

Target	Capture	Replay presses	How
Android TV emulator	✅	✅ everything	`adb -s <serial> shell input keyevent`
Android TV device	✅	✅ everything	the same, over `adb connect <ip>:5555`
Apple TV simulator	✅	✅ except media keys	`idb ui key` / `ui button` / `ui text`
Apple TV device	✅	❌ record only	no supported host-side injection exists

Capture is pure JavaScript, so recording works everywhere, including retail hardware. That is the record-on-retail workflow: a tester presses the physical remote on a rack device, the macro is built from the app's own event stream, and replay runs against emulators and simulators.

The rest of the suite

None of these needed TV-specific code — they are the same tools the phone examples use, available for inspection through the corresponding installed packages:

Network · Storage · Console · Env · Routes · Events · React Query · Redux · Zustand · Jotai

Known limits

No on-device UI, at all. Anything that draws on the app to do its job — render highlighting, debug borders, the image overlay — has nothing to draw into on TV.
A retail Apple TV can be recorded, not driven. Apple's only supported path for pressing buttons on physical hardware is an XCUITest runner paired to the device.
No media transport keys on a tvOS simulator. idb ui key speaks the HID keyboard page, which has no usages for play/pause, rewind, fast-forward, next or previous. Those steps report skipped-unsupported, never silently pass. They work on Android.
Typed text never echoes. It rides the platform's keyboard path and reaches the native text field without touching the app's TV event pipe, so a text step is fire-and-wait.
Swipes and pans replay nowhere. There is no touch surface on either platform, so a swipe recorded from a physical Siri remote has no step that can reproduce it.
Tools beyond the list above are untested on TV. Not blocked — just not device-verified yet.

Coming soon

MCP tools for the remote, so an agent can press the D-pad and replay macros.
An XCUITest lane for retail Apple TV — the one target replay cannot reach today.
Macros in CI, with each step's echo as the assertion.

Next: Quick Start.

Overview