ToothFairy Manual

This manual is also available as a PDF (198K) and as multi-page online help.


1   Introduction

AirPods are great, but they don’t work quite as smoothly with Macs as they do iPhones. You can’t tell at a glance whether audio will play from the AirPods or your Mac’s built-in speaker, you have to dig into a Bluetooth submenu to connect, and then you have to go back to the menu to see when the AirPods are ready for use. ToothFairy streamlines this: just click an icon in the menu bar (or press a hotkey) to switch to the AirPods, and the icon always shows whether they’re connected.

Note: ToothFairy works with devices that can be connected via the macOS Bluetooth menu. Please make sure the devices you want to connect have been paired to the system correctly before using them with ToothFairy.

2   Installing and Updating

ToothFairy is available from the Mac App Store.

3   Menus

3.1   The ToothFairy Menu

After clicking on ToothFairy’s Dock icon, you will see the ToothFairy menu at the top-left of the screen, next to the Apple menu.

4   Frequently Asked Questions (FAQ)

4.1   What information should I include when I report a problem?

It will be faster and easier to help you if your e-mail includes the following information:

The version of macOS that you are using
Click on the Apple menu and choose About This Mac.
The version of ToothFairy that you are using
Click on the ToothFairy menu and choose About ToothFairy. (Please do not say “the latest version,” as this is ambiguous.)
Specific error information
Please see Sending in an Error Report.
If something isn’t working as you expect
Please describe what you did, what happened, and what you expected to happen instead. If possible, take a screenshot or two that illustrate the problem (see Sending in Screenshots).
If ToothFairy hangs or freezes
Please see Sending in a “Sample” Report.

4.1.1   Sending in an Error Report

If an error window appeared on your screen, please include the exact text of the error message in your e-mail. (It may help to use Copy and Paste.)

Please also send in any errors that were reported in the system log:

  1. From the ToothFairy Preferences window, click on the About tab. Then click the Save Diagnostic Report button.
  2. Choose a location such as your desktop and click Save. Saving the report may take a minute or so.
  3. Create an e-mail to and drag the Diagnostic Report.tbz file into the e-mail message to include it as an attachment/enclosure.

If you can’t launch ToothFairy, you can access the log directly, rather than using the automated diagnostic reporter:

macOS 10.12 and Later

  1. Click on Finder in the Dock.
  2. From the Go menu, choose Utilities.
  3. Double-click the Console application.
  4. Click on your Mac under Devices at the left side of the window. (It may be necessary to first choose Show Sources from the View menu.)
  5. From the Action menu, choose All Messages. Make sure that Include Info Messages and Include Debug Messages are both unchecked.
  6. If Activities is selected (blue) in the toolbar, click it to turn off activities mode.
  7. If the main part of the window shows any recent error messages, select them (or choose Edit ‣ Select All).
  8. There are two ways to share the selected part of the log with us:
    • Easier: Click the Share button in the toolbar and select Mail. (If you do not use Apple Mail as your mail client, you can instead Copy and Paste the log messages into your mail client.)
    • Preferred: Choose Edit ‣ Copy. Open TextEdit and Paste the text into a new plain text document. Save the TextEdit document to disk and attach it to your e-mail message.

macOS 10.11 and Earlier

  1. Click on Finder in the Dock.

  2. From the Go menu, choose Utilities.

  3. Double-click the Console application.

  4. Click on All Messages at the left of the window. (It may be necessary to first click the Show Log List toolbar button if you don’t see All Messages at the left.)

  5. If it shows any recent error messages, select them (or choose Edit ‣ Select All).

    Note: You may need to click the Earlier button at the bottom of the window to find errors that did not occur recently.

  6. Choose File ‣ Save Selection As… and save the file as My Log.log on your desktop.

  7. Drag this file into your e-mail message to include it as an attachment/enclosure.

4.1.2   Sending in a Bluetooth Log

If the problem is related to connecting or disconnecting via Bluetooth, you can save a Bluetooth diagnostic log by entering this command in Terminal:

sudo /System/Library/Frameworks/IOBluetooth.framework/Resources/BluetoothReporter

Finder will then open a window showing the BluetoothReporter_<date>.tar.gz report file.

4.1.3   Sending in Screenshots

To take a screenshot, hold down the Command and Shift keys and press the number 4. Then use the mouse to select the area of the screen that you want to take a picture of. This will create a file called Screen Shot <date> at <time>.png on your desktop. Pressing the keys again will create Screen Shot <date> at <new time>.png, etc.

You can also take screenshots using the File ‣ Take Screenshot command in the Preview application.

To send in screeenshots, drag the files into your e-mail window to attach them to your message. If you’re using Apple Mail, be sure to set the Image Size pop-up menu at the bottom of the message window to Actual Size.

4.1.4   Sending in a “Sample” Report

If a program is slow, hangs (e.g. with a spinning beachball), or freezes, a “sample” report can record what your Mac was doing in order to locate the source of the problem.

  1. Click on Finder in the Dock.
  2. From the Go menu, choose Utilities.
  3. Double-click the Activity Monitor program.
  4. Select ToothFairy in the Activity Monitor window.
  5. Do whatever it is in ToothFairy that causes the slowness, hang, or freeze. Immediately, click on Activity Monitor in the Dock and choose Sample Process from the View menu.
  6. After Activity Monitor has finished taking the sample, click the Save… button in the “Sample of ToothFairy” window. Save the file to your desktop and then include it in your e-mail message to as an attachment. (Please do not copy and paste the text from the Activity Monitor window.)

4.1.5   Sending in Crash Log Files

Crash logs are stored in the folder:


First click on the Finder in the Dock, then click on the Go menu, and hold down the Option key as you choose Library. Open the Logs folder, then DiagnosticReports.

Once you’ve opened the DiagnosticReports folder, find the most recent crash log file for the app that crashed and add it to your e-mail message to as an attachment.

4.2   Why isn’t my device connecting?

ToothFairy works with devices that can be connected to your Mac via the macOS Bluetooth menu. If you can connect it via the system menu, you should be able to connect and disconnect it via ToothFairy. Here are some steps to try if you can’t get your device to connect:

  1. Make sure that Bluetooth is On in the Bluetooth pane in System Preferences. It can help to turn Bluetooth off and then back on again on your Mac, as well as on other nearby devices.
  2. Make sure that your device is paired with your Mac using the Bluetooth pane of System Preferences. It sometimes helps to unpair the device in System Preferences and then re-pair it.
  3. Make sure the device’s battery is fully charged.
  4. It can help to adjust your AirDrop settings (on your Macs and any nearby iOS devices). Bluetooth devices connect more reliably when AirDrop is off or set to Contacts Only.
  5. Check Apple’s Potential sources of Wi-Fi and Bluetooth interference guide.
  6. Try resetting your Mac’s Bluetooth module. You can do this by holding down the Shift and Option keys while clicking on the Bluetooth menu. Go to the Debug submenu and choose Reset the Bluetooth Module. Then restart your Mac.
  7. If you still can’t get it to work, save a Bluetooth log and a diagnostic report and send them to us for further assistance.

4.3   Why don’t I see the battery level?

If you’ve checked Show battery status in the menu bar in ToothFairy’s preferences, you should see the battery level for any Bluetooth device supported by macOS. macOS has can read the battery level of popular Bluetooth devices such as AirPods, Magic Mouse, Magic Keyboard, and many common headphones and third-party input devices. Some devices report the battery level in a different way that doesn’t show up in the Bluetooth pane of System Preferences even though iOS (which supports more devices than macOS) may be able to show it. Currently, if macOS doesn’t show the battery leve, ToothFairy won’t, either. If you have such a device, please contact us and let us know which device are you using. We may add direct support for popular devices in a future version of ToothFairy.

4.4   Why do I see the Dock icon even after hiding it?

After you’ve checked the Hide Dock icon preference, you need to quit and relaunch ToothFairy in order for the change to take effect.

Also, macOS 10.14 includes a section of the Dock for recent applications, and this can include the icons even of applications that have hidden their icons. To hide ToothFairy from this section, first quit ToothFairy. Then you can either:

  • Click and hold on the ToothFairy Dock icon and choose Options ‣ Remove from Dock from the menu; or
  • Drag the ToothFairy icon off the Dock; or
  • Go to System Preferences ‣ Dock and uncheck Show recent applications in Dock to hide that section entirely.

5   Legal Stuff

Copyright and Trademarks

ToothFairy and this manual are copyright © 2002–2019 by C-Command Software, LLC. All rights reserved.

ToothFairy is a trademark of C-Command Software, LLC. Mac is a registered trademark of Apple Computer. All other products mentioned are trademarks of their respective owners.

End User License Agreement


License Grant

“You” means the person or company who is being licensed to use the Software or Documentation. “We,” “us” and “our” means C-Command Software, LLC.

We hereby grant you a nonexclusive license to use one copy of the Software on any single computer, or on multiple computers only used by a single person. The Software is “in use” on a computer when it is loaded into temporary memory (RAM) or installed into the permanent memory of a computer—for example, a hard disk or other storage device.


We remain the owner of all right, title and interest in the Software and related explanatory written materials (“Documentation”).

Archival or Backup Copies

You may copy the Software for backup and archival purposes, provided that the original and each copy is kept in your possession and that your installation and use of the Software does not exceed that allowed in the “License Grant” section above.

Things You May Not Do

The Software and Documentation are protected by United States copyright laws and international treaties. You must treat the Software and Documentation like any other copyrighted material—for example, a book. You may not:


You may transfer all your rights to use the Software and Documentation to another person or legal entity provided you transfer this Agreement, the Software and Documentation, including all copies, updates and prior versions to such person or entity and that you retain no copies, including copies stored on computer.

Limited Warranty

The software is provided “as is,” without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software. No employee, agent, dealer or distributor of ours is authorized to modify this limited warranty, nor to make any additional warranties.

Term and Termination

This license agreement takes effect upon your use of the software and remains effective until terminated. You may terminate it at any time by destroying all copies of the Software and Documentation in your possession. It will also automatically terminate if you fail to comply with any term or condition of this license agreement. You agree on termination of this license to destroy all copies of the Software and Documentation in your possession.

General Provisions

  1. This written license agreement is the exclusive agreement between you and us concerning the Software and Documentation and supersedes any prior purchase order, communication, advertising or representation concerning the Software.
  2. This license agreement may be modified only by a writing signed by you and us.
  3. This license agreement is governed by the laws of the State of New Hampshire.
  4. You agree that the Software will not be shipped, transferred or exported into any country or used in any manner prohibited by the United States Export Administration Act or any other export laws, restrictions or regulations.


The following open-source components are used in ToothFairy:

6   Version History

2.5—April 17, 2019
  • Added menu bar icons for more devices: pair of AirPods, Powerbeats3, Powerbeats Pro, Beats Solo, headset, speakers (boombox, conference, cylinder, desktop, vertical), graphics tablet, game controller, Magic Mouse, 2-button mouse, Magic Trackpad 2 (top and side views), Magic Trackpad 1 (side view), iPhone, and tablet.
  • Clicking on a device in the menu bar now shows a menu with its name, connection status, and battery level, so you can see the information immediately instead of waiting for the tooltip to appear.
  • The Preferences window now explains that you can right-click (or Control-click) the menu bar icon to access the preferences when the Dock icon is hidden.
  • The Preferences window now explains that showing the battery status requires a device whose battery level appears in the Bluetooth pane in System Preferences.
  • Tweaked various Preferences window text to clarify the icon and audio input settings and how the new Apple H1 chip fits in.
  • Improved the Why don’t I see the battery level? and Why isn’t my device connecting? sections of the manual.
  • When reporting a Bluetooth error, ToothFairy now includes the hex code and error name to help look up the exact cause of the problem.
  • Fixed a regression where changing the icon didn’t work on macOS 10.11.
  • Updated code for Xcode 10.2 and Swift 5.
2.4.9—January 29, 2019
  • ToothFairy no longer shows an error window when you try to connect to a device that’s already connected.
  • ToothFairy now automatically retries connecting via Bluetooth to make it more likely that it will succeed without user intervention.
  • Improved the Why isn’t my device connecting? section of the manual.
  • Added the Why don’t I see the battery level? section of the manual.
  • Added accessibility labels for the device icon menu and menu bar status icon.
  • ToothFairy is more judicious about changing the audio input device, to avoid excessive Micro Snitch notifications.
  • Fixed a bug where some script text could be displayed with the wrong color in Dark Mode.
2.4.8—November 7, 2018
  • If there’s an error connecting to your Bluetooth device, ToothFairy now recommends to you how you can fix it.
  • Improved the wording in various user interface text.
  • Fixed a bug where the menu bar background color when clicking on the menu didn’t match the accent color on macOS 10.14 or the Graphite appearance on earlier versions.
  • Added the Why isn’t my device connecting? and Why do I see the Dock icon even after hiding it? sections of the manual.
  • The Credits sheet now links to the privacy policy.
  • Added accessibility descriptions in the Preferences window.
  • Improved the diagnostic report.
  • Error logging now includes more information about the error and the device it’s related to.
2.4.7—August 14, 2018
  • Added support for Dark Mode on macOS 10.14.
  • Revised various preferences text to improve clarity. For example:
    • Global hotkey to switch connection is now Global hotkey to connect/disconnect.
    • Hide dock icon (effect after next launch) is now Hide Dock icon (takes effect at next launch).
    • Audio output only is now Improve sound quality by disabling audio input.
    • Connection only mode is now Don’t disconnect when clicking icon or pressing hotkey.
  • Fixed a bug where the Audio output only option didn’t work, causing AirPods to be inappropriately set as the system audio input device.
  • Added the Save Diagnostic Report button.
  • Reduced the size of the application by having ToothFairy and its login item helper share the same copy of the Swift libraries.
  • Fixed the minimum widths of the OK buttons.
  • Reformatted the text in the credits sheet with fonts, styles, and clickable links.
2.4.6—July 11, 2018
  • The shell script text views now use a monospaced font for better readability of punctuation characters.
  • The shell script text views now disable automatic quote and dash substitution so that you don’t accidentally get smart punctuation in your scripts.
  • Fixed a bug where opening the Preferences window didn’t always bring it to the front.
  • Fixed a bug where the disconnection script was not run.
  • Fixed a bug where there was extra space at the end of the tooltip when hovering over the menu bar icon.
  • Fixed a bug where some of the menu bar icons were not centered when the battery indicator was visible.
  • Updated the German localization.
2.4.5—June 14, 2018
  • C-Command Software has acquired ToothFairy from the original developer, Yibin (Robin) Lu, who was no longer able to work on the app. We thank Robin for his work and look forward to continuing development of the app.
  • Restored compatibility with macOS 10.11.
  • The right-click menu now appears on mouse down instead of mouse up, for consistency with other menus.
  • Updated the copyright and credits.
  • Renamed the app from Tooth Fairy to ToothFairy.
  • Fixed a bug where the credits sheet didn’t have a minimum width.
  • Removed an .sdef file that’s not actually used.