Docs

On your phone.

FIXME works on your real phone, inside your own app, through a tiny helper that only exists in Debug builds. Your agent gets the exact file and line, the UI tree, the console, the network and clips.

What the helper adds

  • A three finger tap (or a small FIXME tab on the screen edge) that opens the circle overlay in your app.
  • Shake, or tap Clip, to send the last 30 seconds as a clip. Turn on Hands-free in the FIXME menu and you can say "FIXME, clip that" instead.
  • The UI tree, console, network requests and a timeline of taps and hitches in every ticket.

The helper runs in Debug builds only. It is left out of your release builds, and it only talks to your own Mac.

iOS: SwiftUI and UIKit

Needs iOS 16 or later and Xcode 16 or later.

The easy way

Open FIXME on your Mac. In setup, or later in Settings, General, On your phone, choose Add FIXME to your app. FIXME shows you every change before it makes it, and you can undo it any time.

What it changes, in your Xcode project only:

  • Adds the Swift package.
  • Links it into Debug builds only, with -ObjC -framework PointerKit in the Debug configuration's Other Linker Flags. Release builds never contain it.
  • Adds a Debug Info.plist with the Bonjour service _pointer._tcp and the Local Network, Microphone and Speech Recognition descriptions iOS asks for.

No source files change, and there's nothing to import or start. The helper starts itself in Debug builds.

By hand

  1. Add the package.In Xcode, File, Add Package Dependencies, and enter https://github.com/fixme-dev/fixme-ios. Use version 0.1.7 or later.
  2. Add it to your app target.When Xcode asks which target gets the PointerKit product, pick your app. With no target, the build can't find the framework and fails to link.
  3. Link it in Debug.In your app target's Build Settings, add -ObjC -framework PointerKit to Other Linker Flags for the Debug configuration only.
  4. Keep it out of Release.In the same Build Settings, add PointerKit.framework and PointerKit.o to Excluded Source File Names for every configuration except Debug, so a Release build neither links nor embeds it.
  5. Add the Info.plist keys.For Debug: NSBonjourServices with _pointer._tcp, plus NSLocalNetworkUsageDescription, NSMicrophoneUsageDescription and NSSpeechRecognitionUsageDescription.

Android: Kotlin, Compose and Views

Needs Android 7 (API 24) or later, Android Gradle Plugin 8 and Kotlin 2. It's served from FIXME's own Maven repository at maven.getfixme.dev, only for FIXME's group.

The easy way

Choose Add FIXME to your app in FIXME's setup, the same as for iOS. It makes the two edits below and can undo them.

By hand

  1. Add the repository.In settings.gradle.kts, inside dependencyResolutionManagement { repositories { ... } }, add maven { url = uri("https://maven.getfixme.dev"); content { includeGroup("dev.getfixme") } }. An older project that keeps repositories in the root allprojects block gets the line there.
  2. Add the helper to Debug only.In your app module's build.gradle.kts: debugImplementation("dev.getfixme:fixme-android:0.1.5").

No source files change. A provider in the library starts the helper in Debug builds, and because it's debugImplementation, release builds never contain it. The helper brings its own small fixme-core library from the same repository, which is why one includeGroup line covers both.

React Native and Expo development builds

Needs React Native 0.72 or later, or Expo SDK 47 or later, in a development build (iOS 16 or later, Android 7 or later). The overlay is FIXME's own native one, the same you get in a Swift or Kotlin app, with your React components named in the ticket. It runs only in development: in production builds every export is a no-op and the native part is not linked at all. Expo Go isn't supported, because it can't load native code: there the helper does nothing and prints one line saying it needs a development build (npx expo run:ios or run:android, or an EAS development build).

The easy way

Choose Add FIXME to your app in FIXME's setup, the same as for iOS. It shows you the change first, installs the release for the version FIXME expects from FIXME's GitHub as a development dependency, adds one line to your entry file, and can undo it.

By hand

The helper is a release of github.com/fixme-dev/fixme-react-native, not an npm package. From your project folder, once, this one command installs it as a development dependency with your package manager (npm, Yarn, pnpm or Bun, read from your lockfile) and, only when that worked, adds one line to your entry file:

npx --package https://github.com/fixme-dev/fixme-react-native/releases/latest/download/fixme-react-native.tgz fixme-react-native init

Your package.json then names the release by version, so teammates and CI install the same file, and your lockfile records its checksum. npx fixme-react-native undo removes everything init added. To add the dependency yourself, put that release's address in package.json and run your package manager's install, then run npx fixme-react-native init. npx expo install doesn't accept an address, so in an Expo project use your package manager for this step.

The line it adds, as the first statement of your entry file:

if (__DEV__) require('fixme-react-native/auto');

For an Expo Router app it writes an index.js that loads the helper first and then expo-router/entry, and points "main" at it. undo puts it back.

Expo: init also adds "fixme-react-native" to the plugins in app.json (with an app.config.js, add it there by hand). The plugin adds the Bonjour, Local Network and microphone texts iOS needs. Because the overlay is native code, run npx expo run:ios or run:android (or build a new EAS development build) once: a reload doesn't add it.

Bare React Native: init adds the same Info.plist texts and runs pod install; Android links itself. The native part is linked into Debug builds only. Rebuild the app once afterwards.

Flutter

Needs Flutter 3.10 or later (Dart 3). With FIXME on your Mac, a Flutter debug build started with flutter run already works with no package: circle on the Mac and FIXME reads the exact file and line. Add the helper to circle on the phone itself. It's served from FIXME's GitHub, not pub.dev.

The easy way

Choose Add FIXME to your app in FIXME's setup. It shows you the change first, adds the dependency, the import and the one-line wrap below, and can undo them.

By hand

Add the helper as a development dependency, from its Git repository, and wrap your root widget:

# pubspec.yaml
dev_dependencies:
  fixme_flutter:
    git:
      url: https://github.com/fixme-dev/fixme-flutter.git
      ref: v0.1.5

// lib/main.dart
import 'package:fixme_flutter/fixme_flutter.dart'; // ignore: depend_on_referenced_packages

void main() => runApp(FixmeFlutter.wrap(const MyApp()));

Then run your app with flutter run or your IDE's Run button. Those record where each widget was created, which is how FIXME finds the file and line; a build made with flutter build ios --debug doesn't, and FIXME says so in the ticket instead of guessing. In profile and release builds wrap returns your app unchanged and the helper is left out. (The comment on the import silences an analyzer lint about importing a development dependency; add the package under dependencies: instead if you prefer a clean analyzer.)

iOS: the first build runs pod install by itself, and the overlay is linked into Debug configurations only. It needs iOS 16 or later. On a real iPhone, iOS asks before an app may look for your Mac on the Wi-Fi, so add NSLocalNetworkUsageDescription and NSBonjourServices (_pointer._tcp) to ios/Runner/Info.plist, plus NSMicrophoneUsageDescription and NSSpeechRecognitionUsageDescription if you want to talk to the phone. The Mac app's installer adds them for you, and the Simulator needs none.

Android: nothing to add. The helper's Android library has a debug variant that brings in FIXME's Android helper from maven.getfixme.dev (limited to FIXME's own group) and release and profile variants that contain nothing.

Connect your phone

Run your app's Debug build on a phone or the Simulator, with FIXME open on your Mac. Use the same Wi-Fi, or plug the phone in.

  1. Add FIXME to your app.Once, with the steps above.
  2. Run your app.Build the Debug configuration to a phone or the Simulator. A small FIXME is on chip shows under the island.
  3. Allow it.The first time, tap Allow when iOS asks to find devices on your network. Then your Mac and the phone show the same 4 digit code. If they match, press Allow on the Mac.
A hand holds a real phone and the shot pushes in, with a small caption: On your real phone. The iOS Local Network alert and Allow, then the same code 4821 on the phone and on the Mac, with a caption On your Mac. Allow on the Mac, and a green check says the iPhone is connected. A hand holds a real phone and the shot pushes in, with a small caption: On your real phone. The iOS Local Network alert and Allow, then the same code 4821 on the phone and on the Mac, with a caption On your Mac. Allow on the Mac, and a green check says the iPhone is connected.

A phone is approved once and remembered. You can forget it in FIXME, Settings, Network. Until a phone is approved, nothing it sends is delivered to your agent.

A plugged-in iPhone is also recorded by your Mac for clips, at full quality. macOS files that under Camera, and FIXME only uses it for that. It never uses your Mac's camera.

Using it

  • Circle: tap with three fingers (or the FIXME tab on the edge), circle what's wrong with your finger, say it or type it, and send.
  • Clip: shake the phone or tap Clip, or say "FIXME, clip that" once you have turned on Hands-free (off by default; while it is on, your Mac shows the orange mic icon). Review it on your Mac, circle moments, send. Plugged in, the clip is recorded from the phone's screen at 60 fps with no sound, and macOS shows the orange mic icon while it records. Over Wi-Fi the clip comes from the app at a lower frame rate.
  • Away from home: if your Mac can't be reached on your network, the phone uses an end-to-end encrypted relay, or saves tickets and sends them when your Mac is back.
A hand holds a real phone and the shot pushes in, with a small caption: On your real phone. Three fingers tap a settings screen, FIXME's overlay opens, a fingertip circles an icon and a note is sent to Claude Code. A hand holds a real phone and the shot pushes in, with a small caption: On your real phone. Three fingers tap a settings screen, FIXME's overlay opens, a fingertip circles an icon and a note is sent to Claude Code.

Release builds

The iOS helper is compiled only when DEBUG is set and linked only in the Debug configuration, and the Android helper is a debugImplementation dependency. The React Native helper swaps itself for a no-op when __DEV__ is false, and the Flutter helper's wrap returns your app unchanged outside debug builds. To check, archive or bundle your app and look for the string PointerKit in an iOS binary, for fixme-react-native in your JavaScript bundle, or for dev.fixme in your release APK. It should not be there.

Troubleshooting

The phone can't find my Mac

Check that both are on the same Wi-Fi and that Local Network is allowed for your app in iOS Settings, Privacy and Security, Local Network. A VPN on either side can hide devices from each other. Plugging the phone in works too. Doctor, in the FIXME menu, shows what it can see.

My phone says it is waiting for approval

Look at your Mac for the approval panel with the 4 digit code. Press Allow if it matches the one on the phone.

Tickets are saved but not sent

They are held in the phone's outbox and sent when your Mac is reachable again. The FIXME tab on the screen edge shows how many are waiting.