Buoy: a floating dev menu that ships inside your React Native app

The gap Buoy is trying to close in React Native debugging

React Native debugging usually splits across two places. The JS side lives in Chrome DevTools or a terminal, the native side lives in Xcode or Android Studio, and the device in your hand shows you the result but not the cause. Getting a request log off a physical phone typically means a cable, a running Metro server, and a build that is not a release build. Buoy's answer is to move the inspectors into the app process itself. The README describes it as a floating dev menu that ships inside the app, with every request, state change, render and frame visible on the phone, on the desktop, and inside Claude or Cursor. The intended audience is React Native and Expo developers who debug on real hardware, plus QA and support people who need to reproduce a state without a development environment. The tool list leans toward the questions that come up late in a project: why a screen re-rendered, which image wasted memory, why a Sentry event never arrived, which timer is eating the JS thread.

One component, one session, three consumers

The architecture described in the README is a single live session with three entry points. Every tool runs inside the app's process, and the phone, the desktop app and the agent all read the same session. On the phone you tap the floating menu. Buoy Desktop, a separate repository, mirrors the on-device tools into full-screen panels on macOS, Windows and Linux and adds a UI and JS FPS, CPU and memory HUD plus remote control of the device. The MCP server exposes structured tool calls into the running app for Claude Code, Cursor or any MCP editor. Tool discovery is automatic: install a tool package and it appears in the menu on its own. That is the design decision worth noting. Rather than one monolithic package with a growing config surface, Buoy splits into per-tool packages such as @buoy-gg/network, @buoy-gg/storage and @buoy-gg/perf-monitor. It keeps install size down and lets you add one inspector at a time, but it also means the menu is only as useful as the packages you remembered to install. The README notes most tools need zero config, while a few take one line, such as passing zustandStores or calling watchAtoms().

Installing Buoy and getting the floating menu on screen

The README's Quick Start is two steps. Install the core package from npm, then render the component once inside your app tree. The package name is @buoy-gg/core and the exported component is FloatingDevTools.

npm install @buoy-gg/core

Then wrap your existing app output. The README's example keeps the app and the dev menu as siblings inside a fragment, so the menu floats above whatever you already render.

import { FloatingDevTools } from "@buoy-gg/core";

export default function App() {
  return (
    <>
      {/* Your app */}
      <FloatingDevTools />
    </>
  );
}

After that, a floating dev menu appears inside the app. To add an inspector, install its package and it auto-appears in the menu. The README gives two examples of tools that need a line of configuration rather than none: passing zustandStores, and calling watchAtoms(). One caveat is stated plainly in the README: every tool works without a key at reduced capture, and a free key obtained through npx buoy login, with no card, restores the full free tier.

npx buoy login

So the first real use is not just seeing the menu, it is deciding whether the reduced capture is enough for your case before you assume the tool is broken.

Where the free tier stops and Pro begins

This is the part of the README that deserves the most attention before adoption, because it changes what the tool can do rather than how it looks. The README states that every tool is free, and that Pro unlocks production builds, the MCP server and unlimited capture. Those three items are not small. Production builds matter if your bugs only reproduce in a release build, which is common for performance and memory issues. The MCP server is the entire agent story: the README describes the MCP server as what gives Claude Code, Cursor or any MCP editor structured tool calls into the running app, so without Pro the headline claim about your agent driving the app does not apply. Unlimited capture matters because reduced capture can hide the request or the render you were looking for. The README does not document what the reduced capture limits are in numeric terms, so the honest position is that you should measure your own session against the free tier before deciding. Pricing is linked from the README to buoy.gg/pricing rather than stated in the repository.

The licence is the weakest documented part of the repository

The repository's licence field reports NOASSERTION, which means the licence could not be identified automatically from the repository metadata. A LICENSE file exists at the top level, but the README does not state its contents, and the README does not discuss licensing at all. For a package you install into an app, that is the first thing to resolve, not the last. If you are shipping a commercial product, you need to read the LICENSE file and the terms on buoy.gg directly, and you should check whether the per-tool packages carry the same terms as @buoy-gg/core. This is not legal advice and it is not a judgement about the terms, only a statement that the repository metadata does not tell you what they are. The same caution applies to upgrade cost. The repository shows three releases in the recent list, v3.0.1 and v2.2.0 both dated 2026-05-28, and v2.1.15 dated 2026-05-06. The jump from 2.x to 3.x on the same day as a 2.2.0 release suggests a fast-moving version line. The README does not document a migration guide or a deprecation policy, so pinning versions and reading release notes before upgrading is the practical posture.

When Buoy is the wrong tool

Two cases stand out. The first is a project that cannot add a component to the app tree in the environments where the bug appears. Buoy's whole model depends on the dev menu running inside the process, so if your constraint is that nothing extra ships in the bundle, this is not the tool. The second is a team that needs the full inspector set without a login or a paid tier. The README is explicit that tools work without a key at reduced capture, and that production builds and the MCP server sit behind Pro. If your debugging happens mostly in release builds, the free tier will not cover it. There is also a practical limit around the tool count. The repository description says 15 tools while the README body says 22, with Scenarios listed as coming soon and Ask Buoy listed as beta. Counting what is actually shipped against what is announced is worth doing before you plan a workflow around a specific inspector. The README does not document rollback behaviour for the Time Machine snapshots beyond describing restore points and a wipe to fresh install.

How Buoy differs from a browser-based React Native debugger

The obvious alternative is a browser-based debugger attached over a Metro connection, which is what most React Native developers already have. The difference is where the inspector runs. A browser debugger needs a development build, a running bundler and a connection between the two, and it sees the JS side. Buoy runs in the app process, so the README's claim is that it works on any device with no cable, no desktop app and no Metro, and that it covers dev, staging and production builds. That matters most in the situations where a browser debugger is least convenient: a QA phone on a staging build, a release build that only fails on one Android device, or a support engineer who needs to see storage contents without a development environment. The trade-off is that you are adding a component and a set of packages to the app you are debugging, and the agent integration depends on a paid tier. A browser debugger has neither of those properties. For a project that already has a stable Metro-based workflow and no need to inspect release builds, the alternative is simpler and already installed.

What the 22 tool packages actually cover

The README's table is the most concrete part of the repository, and it is worth reading as a list of debugging questions rather than features. Network captures requests, responses, timings and errors, and extracts GraphQL operations into a readable form. Storage browses and edits AsyncStorage, MMKV and SecureStore with change history, and the README notes biometric keys are listed but never auto-read, which is a deliberate constraint worth respecting. Time Machine snapshots storage, Redux, Zustand, Jotai and the query cache as restore points. Highlight Updates attributes each render to mount, state, props or parent, down to the useState before and after. JS Top presents a ranked table of which timers, Promise chains and callbacks consume JS FPS. Images reports cache verdicts and an oversize and wasted-memory audit. Assets lists bundled images, fonts, video and audio with sizes, duplicates and never-loaded detection. Events builds one timeline across every tool with export presets including Markdown for agents and an errors-only view. Console brings a Chrome-DevTools-style console on device, readable from a release build. The breadth is the argument for the package split, and the split is the argument for checking what you have actually installed before you conclude a tool is missing.

Editorial conclusion

Adopt Buoy if you already have a React Native or Expo app and you want network, storage, render and performance inspection available on the device itself, without a cable, a Metro connection or a desktop app in the loop. Skip it if you need a fully permissive licence you can read in one pass, or if your workflow is built entirely around a browser-based debugger and you have no reason to add a component to your app tree. Before committing, verify three things: the exact licence terms for the packages you plan to ship, whether the free tier's reduced capture covers the data you actually need, and whether production builds are a requirement, because the README places them behind Pro. The repository was last pushed on 2026-09-04 and is not archived.

Frequently asked questions

Official sources

1. Buoy-gg/buoy on GitHub
2. Issues
3. Project website
4. README
5. Releases