RSS
Built with Claude

Claude Code helps unlock AirPods 3 head tracking on Linux

Matteo Gaudioso used Claude Code to work out why AirPods 3 hide their motion sensors from Linux. The result, MousePods, turns head movement into a mouse, a sim-racing head tracker and spatial audio. What was found, how to install it and what still doesn't work.

shallow focus photo of Apple AirPods
Photo by Daniel Romero on Unsplash

Updated November 20, 2026: Expanded with the technical findings, install steps, supported devices and limits.

MousePods turns the motion sensors in AirPods into cursor input on Linux. The catch was AirPods 3: on Linux they would not expose those sensors, and the README says LibrePods and four other head-tracking projects listed AirPods 3 as untested or unsupported. Working with Claude Code as a pair engineer, developer Matteo Gaudioso found out why. MousePods is open source: the code is Apache-2.0, while the findings, documentation and captures are CC BY 4.0, which asks for credit and a link on any reuse. The README also notes the project is not affiliated with Apple.

What was blocking AirPods 3

The README lists three findings that, it says, nobody had written down before:

  • AirPods 3 ignore SensorDataWX, the protocol AirPods Pro 2, Pro 3 and AirPods 4 use for motion data.
  • They expose their sensors instead as virtual HID devices through Apple's RemoteHID protocol, on RTBuddy channel 0x800. The project now documents that wire format.
  • At Linux's default L2CAP MTU of 672 bytes, the buds never announce their motion sensors. At 2582, the value iOS uses, they appear.

Along the way the project catalogued the AirPods 3 sensors and reached sample rates of up to about 210 Hz, against the 25 Hz seen before. The findings, with evidence and a list of things not yet isolated, are in docs/DISCOVERIES.md.

What Claude did

A Built with Claude section spells out the split. In one afternoon, Claude ran the Bluetooth probes, including about 300 blind attempts that failed. It also sent background agents through LibrePods, a Wireshark dissector, clone firmware and pseudocode from Apple's iOS RemoteHID framework. Claude found the MTU and RemoteHID keys, wrote the controller, the app and the tests, and kept a journal of every attempt. Gaudioso writes that he held the AirPods, made the calls and checked every result on real hardware. According to the README, the method, failures included, is in that journal in the repo.

How it works

MousePods connects to the buds over L2CAP PSM 0x1001 without root, using an encrypted link with a receive MTU of 2582. It starts the sensor stream through RemoteHID on AirPods 3, where a 58-byte InputReport block arrives at about 100 Hz, or SensorDataWX on the Pro models, detecting which automatically. Gyro and gravity data become yaw, pitch and roll that do not depend on how the bud sits in your ear. A virtual uinput device then moves the cursor at 120 Hz with smoothing, so it works on Wayland as well as X11.

There are three modes: an air mouse driven by head tilt, a pointer you aim at the screen after a two-corner calibration, and an experimental glide mode where you slide a bud on the table. Clicks come from a stem press, a quick head tilt or dwell.

How to install it

The quick route is the Flatpak, after pairing the AirPods with the PC:

flatpak install --user https://starman-tech.github.io/mousepods/MousePods.flatpakref

A first-run wizard handles setup, and updates arrive through flatpak update. Running from source needs Linux with BlueZ, AirPods paired and connected, and write access to /dev/uinput; no root. As with any third-party code, check the repository before you run it:

git clone https://github.com/starman-tech/mousepods && cd mousepods
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python airpods_mouse_controller.py --ui

Most desktop distributions grant /dev/uinput access to the logged-in user. The --diag flag shows live sensor rates without taking over the cursor. The README advertises 400+ tests that need no hardware. On immutable systems such as Bazzite, it recommends a Fedora distrobox; SteamOS should work the same way but is untested.

Beyond the mouse

The project has grown past its first goal. A Games page lets Steam games running under Proton follow your head without opentrack, by placing a small TrackIR/FreeTrack DLL in the game's prefix. A contributor tested this in Assetto Corsa and Euro Truck Simulator 2 with AirPods Pro 2. Flight sims can use the opentrack UDP output on 127.0.0.1:4242. A virtual joystick for native Linux games exists, but its axes have been tested and it has not yet been tried in a game. There is also a 360-degree video player.

Spatial audio

Switch on Spatial audio in the app and play anything through the MousePods Spatial output. Sound is rendered in 3D in the AirPods and stays fixed in the room as you turn your head, so stereo sounds like two speakers on your desk.

Limits

  • Verified on hardware: AirPods 3, AirPods Pro 2 and AirPods Pro 3. AirPods 4, AirPods Max and first-generation Pro are untested; AirPods 1 and 2 have no head-tracking sensors.
  • Head tracking is rotation only (3 degrees of freedom); yaw is recentred by hand.
  • Pointer mode has only been tested in simulation, and glide mode will never match an optical mouse, the README says.
  • Windows is experimental: the sensor stream and --diag work through a test-signed driver, but there is no mouse yet. macOS doesn't need it, since Apple's own API already offers head tracking. Android is not supported yet, because it needs a Bluetooth stack that allows the AirPods channel.
  • AirPods 3 sensors are off while the buds are in the case. Sony and Pixel Buds headsets are experimental, and an optional Garmin watch module pulls in an AGPL-3.0 dependency.

Our take

In our view, the published findings and protocol notes are worth as much as the tool itself, since other projects such as RustPods are already building on the RemoteHID work. The Built with Claude section is also a clear record of how the work was split: Claude ran about 300 failed blind attempts and the background research in an afternoon, while Gaudioso held the hardware and made the calls.

Built by Matteo Gaudioso

Source: MousePods on GitHub (starman-tech/mousepods)

This story first appeared in the claudefox daily briefing for November 8, 2026.